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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

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

get

/kyc-forms

HTTPcURLJavaScriptPython

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-12-16T19:06:18.367Z",
      "updatedAt": "2025-12-16T19:06:18.367Z"
    }
  ]
}

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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstringRequired

The organization ID

kycFormIdstring · uuidRequired

Body

application/json

keystringRequired

The question key to upload the file for.

Responses

201

OK

application/json

403

Forbidden operation

application/json

404

Resource not found

application/json

422

Request validation failed

application/json

post

/organizations/{organizationId}/kyc-forms/{kycFormId}/files

HTTPcURLJavaScriptPython

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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstringRequired

The organization ID

kycFormIdstring · uuidRequired

Body

application/json

anyOptional

or

anyOptional

Responses

201

OK

application/json

403

Forbidden operation

application/json

404

Resource not found

application/json

422

Request validation failed

application/json

post

/organizations/{organizationId}/kyc-forms/{kycFormId}/entries

HTTPcURLJavaScriptPython

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-12-16T19:06:18.367Z",
  "displayName": "text",
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "updatedAt": "2025-12-16T19:06:18.367Z"
}

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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

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

application/json

or

or

Responses

200

OK

application/json

Responseone of

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

or

or

or

or

403

Forbidden

application/json

404

Not Found

application/json

422

Validation Error

application/json

put

/workspaces/{workspaceId}/endpoints/{endpointId}/compliance-requirements/{requirementName}

HTTPcURLJavaScriptPython

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-12-16T19:06:18.367Z",
  "issues": [
    "subscription-is-not-active"
  ],
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "type": "kyc-form",
  "capabilities": [
    "voice"
  ],
  "destinations": [
    "text"
  ],
  "managedBy": "text",
  "appliesTo": "endpoint",
  "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-12-16T19:06:18.367Z",
      "updatedAt": "2025-12-16T19:06:18.367Z"
    }
  ],
  "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-12-16T19:06:18.367Z",
    "displayName": "text",
    "tags": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "updatedAt": "2025-12-16T19:06:18.367Z"
  }
}

Example request

Get formEntryId from kyc-forms

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

organizationId string required

Example request to link Local Brand Identification

PUT https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/compliance-requirements/brand:au

workspaceId string required

endpointId string required

{
    "formEntryId":"{formEntryId}",
    "formId":"4d74e9c0-3f3b-4d5f-8983-b343ecac3986",
    "type":"kyc-form"
}