Identities

Create new identity

Create an identity for an individual or an organization.

POST/identities

Authorization

If set, the API uses an API key for authentication. Include the following header in your requests: X-blnk-key: <api-key>.

Replace <api-key> with your secret API key. Ensure the key is kept secure and not exposed in public repositories or client-side code.

Body

identity_idstringbody

Your own identity id. When you send it, it must start with idt_ and a valid UUID, for example idt_11111111-1111-4111-8111-111111111111. Leave it out and Blnk generates one. A duplicate id returns 400 with IDT_VALIDATION_ERROR.

identity_typestringbody

individual or organization.

organization_namestringbody

Name of the organization.

first_namestringbody

First name of the individual.

last_namestringbody

Last name of the individual.

other_namesstringbody

Response

The response is the identity Blnk stored. created_at is set by Blnk. A field you omit comes back empty.

identity_idstringrequired

Id of the created identity.

identity_typestring

individual or organization.

organization_namestring

Name of the organization.

first_namestring

First name of the individual.

last_namestring

Last name of the individual.

other_namesstring

Other names linked to the individual.

genderstring

Gender of the individual.

dobstring

Date of birth.

email_addressstring

Email address of the identity.

phone_numberstring

Contact number of the identity.

nationalitystring

Nationality of the individual.

categorystring

Label stored for this customer.

streetstring

Street address of the identity.

countrystring

Country of the identity.

statestring

State or region of the identity.

post_codestring

Postal code of the identity.

citystring

City of the identity.

created_atstringrequired

When Blnk created the identity.

meta_dataobject

Custom metadata linked to the identity.

curl -X POST "http://localhost:5001/identities" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "idt_11111111-1111-4111-8111-111111111111",
    "identity_type": "individual",
    "first_name": "Alice",
    "last_name": "Smith",
    "other_names": "Marie",
    "gender": "female",
    "dob": "1985-05-15T00:00:00Z",
    "email_address": "[email protected]",
    "phone_number": "+1234567890",
    "nationality": "Canadian",
    "category": "customer",
    "street": "789 Elm St",
    "country": "Canada",
    "state": "Ontario",
    "post_code": "M4B 1B3",
    "city": "Toronto",
    "meta_data": {
      "customer_id": "CUST123456",
      "membership_level": "Gold"
    }
  }'

{
  "identity_id": "idt_11111111-1111-4111-8111-111111111111",
  "identity_type": "individual",
  "organization_name": "",
  "first_name": "Alice",
  "last_name": "Smith",
  "other_names": "Marie",
  "gender": "female",
  "dob": "1985-05-15T00:00:00Z",
  "email_address": "[email protected]",
  "phone_number": "+1234567890",
  "nationality": "Canadian",
  "category": "customer",
  "street": "789 Elm St",
  "country": "Canada",
  "state": "Ontario",
  "post_code": "M4B 1B3",
  "city": "Toronto",
  "created_at": "2024-11-26T08:36:36.238244338Z",
  "meta_data": {
    "customer_id": "CUST123456",
    "membership_level": "Gold"
  }
}

{
  "error": "identity_id suffix after 'idt_' must be a valid UUID",
  "error_detail": {
    "code": "IDT_VALIDATION_ERROR",
    "message": "identity_id suffix after 'idt_' must be a valid UUID"
  }
}

{
  "error": "Identity already exists: idt_11111111-1111-4111-8111-111111111111",
  "error_detail": {
    "code": "IDT_VALIDATION_ERROR",
    "message": "Identity already exists: idt_11111111-1111-4111-8111-111111111111"
  }
}