Characters - Grant Character To User

Grants the specified character type to the user. CharacterIds are not globally unique; characterId must be evaluated with the parent PlayFabId to guarantee uniqueness.

POST https://titleId.playfabapi.com/Client/GrantCharacterToUser

Request Header

Name Required Type Description
X-Authorization True

string

This API requires a client session ticket, available from any Client Login function.

Request Body

Name Required Type Description
CharacterName True

string

Non-unique display name of the character being granted (1-40 characters in length).

ItemId True

string

Catalog item identifier of the item in the user's inventory that corresponds to the character in the catalog to be created.

CatalogVersion

string

Catalog version from which items are to be granted.

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

Responses

Name Type Description
200 OK

GrantCharacterToUserResult

400 Bad Request

ApiErrorWrapper

This is the outer wrapper for all responses with errors

Security

X-Authorization

This API requires a client session ticket, available from any Client Login function.

Type: apiKey
In: header

Definitions

Name Description
ApiErrorWrapper

The basic wrapper around every failed API response

GrantCharacterToUserRequest

Grants a character to the user of the type specified by the item ID. The user must already have an instance of this item in their inventory in order to allow character creation. This item can come from a purchase or grant, which must be done before calling to create the character.

GrantCharacterToUserResult

ApiErrorWrapper

The basic wrapper around every failed API response

Name Type Description
code

integer

Numerical HTTP code

error

string

Playfab error code

errorCode

integer

Numerical PlayFab error code

errorDetails

object

Detailed description of individual issues with the request object

errorMessage

string

Description for the PlayFab errorCode

status

string

String HTTP code

GrantCharacterToUserRequest

Grants a character to the user of the type specified by the item ID. The user must already have an instance of this item in their inventory in order to allow character creation. This item can come from a purchase or grant, which must be done before calling to create the character.

Name Type Description
CatalogVersion

string

Catalog version from which items are to be granted.

CharacterName

string

Non-unique display name of the character being granted (1-40 characters in length).

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

ItemId

string

Catalog item identifier of the item in the user's inventory that corresponds to the character in the catalog to be created.

GrantCharacterToUserResult

Name Type Description
CharacterId

string

Unique identifier tagged to this character.

CharacterType

string

Type of character that was created.

Result

boolean

Indicates whether this character was created successfully.

Error Codes

Name Code
InvalidItemProperties 1091
ItemNotOwned 1048