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
400 Bad Request

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

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