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:

List all kyc-forms: Australian kyc-formID is 4d74e9c0-3f3b-4d5f-8983-b343ecac3986
Get upload token: This action gets info to upload image to bucket.
Upload proof of address image: This action submits image to bucket.
Link Proof Of Address information: This action links Proof Of Address.
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

application/json

Responseall of

get

GET /kyc-forms HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

200

{
  "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-29T18:16:15.365Z",
      "updatedAt": "2025-08-29T18:16:15.365Z"
    }
  ]
}

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

application/json

403

Forbidden operation

application/json

404

Resource not found

application/json

422

Request validation failed

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

application/json

403

Forbidden operation

application/json

404

Resource not found

application/json

422

Request validation failed

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-29T18:16:15.365Z",
  "displayName": "text",
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "updatedAt": "2025-08-29T18:16:15.365Z"
}

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

Responses

200

application/json

Responseone of

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

all ofOptional

and

all ofOptional

and

all ofOptional

and

all ofOptional

and

all ofOptional

and

403

Forbidden

application/json

404

Not Found

application/json

422

Validation Error

application/json

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-29T18:16:15.365Z",
  "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-29T18:16:15.365Z",
      "updatedAt": "2025-08-29T18:16:15.365Z"
    }
  ],
  "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-29T18:16:15.365Z",
    "displayName": "text",
    "tags": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "updatedAt": "2025-08-29T18:16:15.365Z"
  }
}

Example request

Get formEntryId from kyc-forms

GET https://app.bird.com/api/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"
}

Last updated 16 days ago

Was this helpful?