Custom User Data API

This API allows a service provider to store and manage custom data associated with a user. Custom user data is stored according to the user's Alias, which may be shared across multiple Client Applications for each service provider. An Alias can be set once for a user for each Client Application using a /session-feedback request. The Custom User Data API can then be used to store and manage data corresponding to the Alias associated with the access token passed in the /custom-user-data request.

Update Custom Data

Custom data associated with a user can be updated by sending a POST or PATCH request to the /custom-user-data endpoint.

HTTP Request

Custom user data can be updated by sending a POST or PATCH request to the following endpoint:

https://<host-name>/custom-user-data

where <host-name> has the following value depending on the environment:

  • Sandbox: api.bindid-sandbox.io
  • Production: api.bindid.io

Request Headers

The POST or PATCH request must include the following HTTP headers:

Header NameDescription
AuthorizationIncludes authorization for API access. For the header structure, see Authorization.
Content-TypeShould be set to application/json.

Request Parameters

The body for this POST or PATCH request is a JSON object, with the following field:

ParameterDescriptionType
dataRequired. Object containing data that will replace the data in the store for POST, or will update the data in the store for PATCH (as per RFC-7386).Object

Request Example

POST /custom-user-data HTTP/1.1
Content-Type: application/json
Authorization: BindIdBackend AccessToken [hjg2khf236ghf;] Zgoptaz...c1lYTM3..Dg4NYzND...MjQ4hNg
{
"data": {
"account_type": "VIP"
}
}

Response Headers

The POST or PATCH response includes the following HTTP headers:

Header NameDescription
Content-TypeReturns application/json

Response Body

A successful response is an HTTP 200 response. The JSON object in the body has the following structure:

Field NameDescriptionType
status_codeMust be "ok"String

Response Example

HTTP/1.1 200 OK
Content-Type: application/json
{
"status_code": "OK"
}

Failures

In addition to the common errors (see Errors), the following applicative error response codes may be returned as part of a 200 response:

Response CodeDescription
size_exceededData store for the service provider is too big.
invalid_user_typeAttempt to update a store for a user that doesn’t have an Alias for the Client Application corresponding to the access token.

Retrieve Custom Data

Custom data associated with a user can be retrieved by sending a GET request to the /custom-user-data endpoint.

HTTP Request

Custom user data can be retrieved by sending a GET request to the following endpoint:

https://<host-name>/custom-user-data

where <host-name> has the following value depending on the environment:

  • Sandbox: api.bindid-sandbox.io
  • Production: api.bindid.io

Request Headers

The GET request must include the following HTTP header:

Header NameDescription
AuthorizationIncludes authorization for API access. For the header structure, see Authorization.

Request Example

GET /custom-user-data HTTP/1.1
Authorization: BindIdBackend AccessToken [hjg2khf236ghf;] Zgoptaz...c1lYTM3..Dg4NYzND...MjQ4hNg

Response Headers

The POST response includes the following HTTP headers:

Header NameDescription
Content-TypeReturns application/json

Response Body

A successful response is an HTTP 200 response. The JSON object in the body has the following structure:

Field NameDescriptionType
status_codeMust be "ok"String
dataObject containing the content of the store that corresponds to the Alias associated with the access token passed in the request.String

Response Example

HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"account_type": "VIP"
}
}

Failures

In addition to the common errors (see Errors), the following applicative error response codes may be returned as part of a 200 response:

Response CodeDescription
invalid_user_typeAttempt to read a store for a user that doesn’t have an Alias for the Client Application corresponding to the access token.