No-code docs

Local Brand Identification

This article describe how to upload Proof of Address image that confirms your address of registration. For example, a utility bill.

Step-by-step process of upload Proof of Address image with API.

To upload there are a few steps:

  1. List all kyc-forms: Get kyc-formId that is related to the country code of your number. For example, for Australian number, look for "countryCode": "AU".

  2. Get upload tokon: This action gets info to upload image to bucket.

  3. Upload proof of address image: This action submits image to bucket.

  4. Upload user information: This action submits user details.

  5. Link Local Brand Identification: This action links Brand identification.

1- List all kyc-forms

List KYC forms

get
Authorizations
Query parameters
limitinteger · min: 1 · max: 100Optional

Limits the number of results to return

Default: 10
reversebooleanOptional

Order in which to retrieve the results

Default: false
pageTokenstringOptional

Pagination token that keeps of track of the current position in the list

countryCodestring · iso3166-1Optional

Filter KYC forms by target country.

scopestring · enumOptional

Filter KYC forms by scope.

Possible values:
Responses
200
OK
application/json
Responseall of
get
GET /kyc-forms HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*
200

OK

{
  "nextPageToken": "text",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "scope": "number",
      "countryCode": "text",
      "conditions": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "status": "draft",
      "defaultLocale": "text",
      "questions": [
        {
          "locale": "text",
          "questions": [
            {
              "type": "bool",
              "key": "text",
              "description": "text",
              "placeholder": "text",
              "displayName": "text",
              "required": true,
              "mapping": "text",
              "format": "none",
              "conditions": [
                {
                  "key": "text",
                  "value": "text"
                }
              ],
              "options": [
                {
                  "key": "text",
                  "value": "text"
                }
              ],
              "timezone": "text"
            }
          ]
        }
      ],
      "gracePeriodDays": 1,
      "createdAt": "2025-08-04T19:49:05.108Z",
      "updatedAt": "2025-08-04T19:49:05.108Z"
    }
  ]
}

2- Get upload token

Generate upload token

post

Generate a pre-signed token that allows a user to upload a file in response to a question.

Authorizations
Path parameters
organizationIdstringRequired

The organization ID

kycFormIdstring · uuidRequired
Body
keystringRequired

The question key to upload the file for.

Responses
201
OK
application/json
post
POST /organizations/{organizationId}/kyc-forms/{kycFormId}/files HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "key": "text"
}
{
  "url": "text",
  "formData": {
    "policy": "eyAiZXhwaXJhdGlvbiI6ICIyMDE1LTEyLTMwVDEyOjAwOjAwLjAwMFoiLA0KICAiY29uZGl0aW9ucyI6IFsNCiAgICB7ImJ1Y2tldCI6ICJzaWd2NGV4YW",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request",
    "x-amz-date": "20151229T000000Z",
    "x-amz-signature": "8afdbf4008c03f22c2cd3cdb72e4afbb1f6a588f3255ac628749a66d7f09699e"
  },
  "expectedFields": [
    "text"
  ]
}

Example body request

{
    "key":"proofOfAddress"
}

3- Upload proof of Address image

Post request to the url from step 2 response.

POST https://global--kyc-file-uploads--xyz--use1.s3.us-east-1.amazonaws.com

form-data in Body

4- Upload user information

Create KYC Form Entry

post
Authorizations
Path parameters
organizationIdstringRequired

The organization ID

kycFormIdstring · uuidRequired
Body
localestring · locale-bcp47Required
businessProfileIdstring · uuidOptional

The ID of an existing Business Profile.

statusstring · enumOptional

The status of the form entry.

Possible values:
displayNamestringOptional
Responses
201
OK
application/json
post
POST /organizations/{organizationId}/kyc-forms/{kycFormId}/entries HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "locale": "text",
  "businessProfileId": "123e4567-e89b-12d3-a456-426614174000",
  "answers": [
    {
      "key": "text",
      "valueString": "text",
      "isDefault": true
    }
  ],
  "status": "draft",
  "displayName": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "formId": "123e4567-e89b-12d3-a456-426614174000",
  "locale": "text",
  "status": "draft",
  "businessProfileId": "123e4567-e89b-12d3-a456-426614174000",
  "businessProfileVersion": 1,
  "answers": [
    {
      "key": "text",
      "valueString": "text",
      "isDefault": true
    }
  ],
  "reviewComment": "text",
  "createdAt": "2025-08-04T19:49:05.108Z",
  "displayName": "text",
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "updatedAt": "2025-08-04T19:49:05.108Z"
}

Example body request

"valueString": url / key

Get url and key information from step 2 response. (2- Get upload token)

{
  "locale": "en",
  "answers": [
    {
      "key": "proofOfAddress",
      "valueString": "https://global--kyc-file-uploads--xyz--use1.s3.us-east-1.amazonaws.com/organization:{{organizationId}/kycForm:{kwc-formId}/question:proofOfAddress/xyz"
    },
    {
      "key": "companyName",
      "valueString": "text"
    },
    {
      "key": "TestName",
      "valueString": "text"
    },
    {
      "key": "describe-your-socks",
      "valueString": "text"
    }
  ],
  "status": "submitted"
}

5- Link Local Brand identification

Update Workspace Endpoint Compliance Requirement

put

Update a specific compliance requirement for an endpoint. An example of requirement name is use-case-sms, kyc-form, brand (general brand identification) and brand:nl (specific, country-level brand identification requirement).

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: d386a801-ee8d-4aba-a7e4-78671bd3b11e
endpointIdstringRequired

Your endpoint ID. In some cases (e.g. Long Code Numbers) this value is equal to the number ID.

requirementNamestringRequiredExample: kyc-form
Body
one ofOptional
all ofOptional
or
all ofOptional
or
all ofOptional
Responses
200
OK
application/json
Responseone of

The compliance requirements associated to the endpoint that must be satisfied.

all ofOptional
and
and
or
all ofOptional
and
or
all ofOptional
and
or
all ofOptional
and
or
all ofOptional
and
put
PUT /workspaces/{workspaceId}/endpoints/{endpointId}/compliance-requirements/{requirementName} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "formId": "123e4567-e89b-12d3-a456-426614174000",
  "formEntryId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "kyc-form"
}
{
  "status": "satisfied",
  "mutable": true,
  "immutableReason": "managed",
  "message": "text",
  "evaluatedAt": "2025-08-04T19:49:05.108Z",
  "issues": [
    "subscription-is-not-active"
  ],
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "type": "kyc-form",
  "capabilities": [
    "voice"
  ],
  "destinations": [
    "text"
  ],
  "managedBy": "text",
  "forms": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "scope": "number",
      "countryCode": "text",
      "conditions": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "status": "draft",
      "defaultLocale": "text",
      "questions": [
        {
          "locale": "text",
          "questions": [
            {
              "type": "bool",
              "key": "text",
              "description": "text",
              "placeholder": "text",
              "displayName": "text",
              "required": true,
              "mapping": "text",
              "format": "none",
              "conditions": [
                {
                  "key": "text",
                  "value": "text"
                }
              ],
              "options": [
                {
                  "key": "text",
                  "value": "text"
                }
              ],
              "timezone": "text"
            }
          ]
        }
      ],
      "gracePeriodDays": 1,
      "createdAt": "2025-08-04T19:49:05.108Z",
      "updatedAt": "2025-08-04T19:49:05.108Z"
    }
  ],
  "formOptions": {
    "ANY_ADDITIONAL_PROPERTY": "123e4567-e89b-12d3-a456-426614174000"
  },
  "formId": "123e4567-e89b-12d3-a456-426614174000",
  "formEntryId": "123e4567-e89b-12d3-a456-426614174000",
  "formEntry": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "formId": "123e4567-e89b-12d3-a456-426614174000",
    "locale": "text",
    "status": "draft",
    "businessProfileId": "123e4567-e89b-12d3-a456-426614174000",
    "businessProfileVersion": 1,
    "answers": [
      {
        "key": "text",
        "valueString": "text",
        "isDefault": true
      }
    ],
    "reviewComment": "text",
    "createdAt": "2025-08-04T19:49:05.108Z",
    "displayName": "text",
    "tags": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "updatedAt": "2025-08-04T19:49:05.108Z"
  }
}

Last updated

Was this helpful?