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: Australian kyc-formID is 4d74e9c0-3f3b-4d5f-8983-b343ecac3986

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

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

  4. Link Proof Of Address information: This action links Proof Of Address.

  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-07T12:23:08.458Z",
      "updatedAt": "2025-08-07T12:23:08.458Z"
    }
  ]
}

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 request

POST https://api.bird.com/organizations/{organizationId}/kyc-forms/4d74e9c0-3f3b-4d5f-8983-b343ecac3986/files

Example body request

{
    "key":"proofOfAddress"
}

3- Upload proof of Address image

Example request

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

Example body form-data request

acl text required

bucket text required

key text required

policy text required

x-amz-algorithm text required

x-amz-credential text required

x-amz-date text required

x-amz-security-token text required

x-amz-signature text required

Content-Type text required

file File required

4- Link Proof Of Address 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-07T12:23:08.458Z",
  "displayName": "text",
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "updatedAt": "2025-08-07T12:23:08.458Z"
}

Example request

organizationId string - uuid required

POST https://api.bird.com/organizations/{organizationsId}/kyc-forms/4d74e9c0-3f3b-4d5f-8983-b343ecac3986/entries

Example body request

Path parameters

organizationId string - uuid required

proofOfAddress string - uuid required

{
  "locale": "en",
  "answers": [
    {
      "key": "proofOfAddress",
      "valueString": "https://global--kyc-file-uploads--151603429280--use1.s3.us-east-1.amazonaws.com/organization:{organizationId}/kycForm:4d74e9c0-3f3b-4d5f-8983-b343ecac3986/question:proofOfAddress/{proofOfAddressId}"
    }
  ],
  "status": "submitted"
}

proofOfAddressId in (2- Get upload token) response

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-07T12:23:08.458Z",
  "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-07T12:23:08.458Z",
      "updatedAt": "2025-08-07T12:23:08.458Z"
    }
  ],
  "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-07T12:23:08.458Z",
    "displayName": "text",
    "tags": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "updatedAt": "2025-08-07T12:23:08.458Z"
  }
}

Last updated

Was this helpful?