DocumentazioneEngagement Platform API
Sign inGet started
Guides
API

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

GET
/kyc-forms
List KYC forms
Parametri di query
limit
integer
Limits the number of results to return.
reverse
boolean
Reverses the order in which the results are returned.
pageToken
string
The cursor that keeps track of the current position in the results.
countryCode
string
Filter KYC forms by target country.
scope
string
Filter KYC forms by scope.
Possible values: number, organization, channel
Payload della risposta
nextPageToken
string
The token to fetch the next page of results. If empty, there are no more results to fetch.
results
array of object
obbligatorio
Mostra attributi secondari
results.conditions
object
results.countryCode
string
results.createdAt
string
obbligatorio
results.defaultLocale
string
obbligatorio
results.gracePeriodDays
integer
results.id
string
obbligatorio
results.name
string
obbligatorio
results.questions
array of object
obbligatorio
Mostra attributi secondari
results.questions.locale
string
obbligatorio
results.questions.questions
array of object
obbligatorio
Mostra attributi secondari
results.questions.questions.conditions
array of object
Mostra attributi secondari
results.questions.questions.conditions.key
string
results.questions.questions.conditions.value
string
results.questions.questions.description
string
results.questions.questions.displayName
string
obbligatorio
results.questions.questions.format
string
obbligatorio
Possible values: none
results.questions.questions.key
string
obbligatorio
results.questions.questions.mapping
string
Map the answer to a contact attribute. If not set, the answer will not be mapped.
results.questions.questions.options
array of object
Mostra attributi secondari
results.questions.questions.options.key
string
results.questions.questions.options.value
string
results.questions.questions.placeholder
string
results.questions.questions.required
boolean
results.questions.questions.timezone
string
results.questions.questions.type
string
obbligatorio
Possible values: bool, boolArray, intArray, float, floatArray
results.questions.questions.formQuestionConfig
object
Mostra attributi secondari
results.questions.questions.formQuestionConfig.stringDatetimeConfig
object
Mostra attributi secondari
results.questions.questions.formQuestionConfig.stringDatetimeConfig.allowTimezoneSelectionByUser
boolean
results.questions.questions.formQuestionConfig.stringDatetimeConfig.datetimeRange
object
obbligatorio
Mostra attributi secondari
results.questions.questions.formQuestionConfig.stringDatetimeConfig.datetimeRange.type
string
Possible values: any, future, past
results.questions.questions.formQuestionConfig.stringDatetimeConfig.defaultTimezone
string
results.questions.questions.formQuestionConfig.stringDatetimeConfig.includeTime
boolean
results.questions.questions.formQuestionConfig.stringDatetimeConfig.localeOverride
string
results.questions.questions.formQuestionConfig.stringDatetimeConfig.timeFormat
string
Possible values: am-pm, 24h
results.questions.questions.formQuestionConfig.stringDatetimeConfig.timePlaceholder
string
results.questions.questions.formQuestionConfig.type
string
Possible values: stringDatetime
results.questions.questions.ui:type
string
hint the UI what form to show if type isn't sufficient
Possible values: shortText, longText, dropdown, radio, checkboxSelect
results.scope
string
obbligatorio
Possible values: number, organization, channel
results.status
string
obbligatorio
Possible values: draft, active, deactivated
results.updatedAt
string
obbligatorio
Esempio di codice
curl -X GET 'https://api.bird.com/kyc-forms' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

2- Get upload token

POST
/organizations/{organizationId}/kyc-forms/{kycFormId}/files
Generate a pre-signed token that allows a user to upload a file in response to a question.
Payload della richiesta
key
string
obbligatorio
The question key to upload the file for.
Payload della risposta
url
string
obbligatorio
URL to post the image to
formData
object
obbligatorio
expectedFields
array of string
Esempio di codice
curl -X POST 'https://api.bird.com/organizations/{organizationId}/kyc-forms/{kycFormId}/files' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Example request
Esempio di codice
POST https://api.bird.com/organizations/{organizationId}/kyc-forms/4d74e9c0-3f3b-4d5f-8983-b343ecac3986/files
Example body request
Esempio di codice
{
    "key":"proofOfAddress"
}

3- Upload proof of Address image

Example request
Esempio di codice
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

POST
/organizations/{organizationId}/kyc-forms/{kycFormId}/entries
Create KYC Form Entry
Payload della richiesta
locale
string
obbligatorio
answers
array of object
obbligatorio
Mostra parametri secondari
answers.isDefault
boolean
answers.key
string
obbligatorio
answers.valueString
string
obbligatorio
status
string
The status of the form entry.
Possible values: draft, submitted, approved, rejected, expired
displayName
string
Payload della risposta
answers
array of object
obbligatorio
Mostra attributi secondari
answers.isDefault
boolean
answers.key
string
obbligatorio
answers.valueString
string
obbligatorio
businessProfileId
string
The ID of an existing Business Profile.
businessProfileVersion
integer
The version of the Business Profile.
createdAt
string
obbligatorio
displayName
string
formId
string
obbligatorio
id
string
obbligatorio
locale
string
obbligatorio
organizationId
string
obbligatorio
reviewComment
string
status
string
obbligatorio
The status of the form entry.
Possible values: draft, submitted, approved, rejected, expired
tags
array of object
Mostra attributi secondari
tags.key
string
obbligatorio
tags.value
string
obbligatorio
updatedAt
string
obbligatorio
Esempio di codice
curl -X POST 'https://api.bird.com/organizations/{organizationId}/kyc-forms/{kycFormId}/entries' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Example request
organizationId string - uuid required
Esempio di codice
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
Esempio di codice
{
  "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

PUT
/workspaces/{workspaceId}/endpoints/{endpointId}/compliance-requirements/{requirementName}
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).
Payload della richiesta
formId
string
formEntryId
string
type
string
obbligatorio
Possible values: kyc-form
Payload della risposta
status
string
obbligatorio
Possible values: satisfied, pending, unsatisfied
mutable
boolean
obbligatorio
immutableReason
string
Possible values: managed, dependency, none
message
string
evaluatedAt
string
issues
array of string
userId
string
name
string
obbligatorio
type
string
obbligatorio
Possible values: kyc-form
capabilities
array of string
obbligatorio
destinations
array of string
managedBy
string
appliesTo
string
Specifies whether this requirement applies to endpoint-level or destination-level evaluation. Empty means both.
Possible values: endpoint, destination
forms
array of object
Mostra attributi secondari
forms.conditions
object
forms.countryCode
string
forms.createdAt
string
obbligatorio
forms.defaultLocale
string
obbligatorio
forms.gracePeriodDays
integer
forms.id
string
obbligatorio
forms.name
string
obbligatorio
forms.questions
array of object
obbligatorio
Mostra attributi secondari
forms.questions.locale
string
obbligatorio
forms.questions.questions
array of object
obbligatorio
Mostra attributi secondari
forms.questions.questions.conditions
array of object
Mostra attributi secondari
forms.questions.questions.conditions.key
string
forms.questions.questions.conditions.value
string
forms.questions.questions.description
string
forms.questions.questions.displayName
string
obbligatorio
forms.questions.questions.format
string
obbligatorio
Possible values: none
forms.questions.questions.key
string
obbligatorio
forms.questions.questions.mapping
string
Map the answer to a contact attribute. If not set, the answer will not be mapped.
forms.questions.questions.options
array of object
Mostra attributi secondari
forms.questions.questions.options.key
string
forms.questions.questions.options.value
string
forms.questions.questions.placeholder
string
forms.questions.questions.required
boolean
forms.questions.questions.timezone
string
forms.questions.questions.type
string
obbligatorio
Possible values: bool, boolArray, intArray, float, floatArray
forms.questions.questions.formQuestionConfig
object
Mostra attributi secondari
forms.questions.questions.formQuestionConfig.stringDatetimeConfig
object
Mostra attributi secondari
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.allowTimezoneSelectionByUser
boolean
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.datetimeRange
object
obbligatorio
Mostra attributi secondari
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.datetimeRange.type
string
Possible values: any, future, past
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.defaultTimezone
string
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.includeTime
boolean
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.localeOverride
string
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.timeFormat
string
Possible values: am-pm, 24h
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.timePlaceholder
string
forms.questions.questions.formQuestionConfig.type
string
Possible values: stringDatetime
forms.questions.questions.ui:type
string
hint the UI what form to show if type isn't sufficient
Possible values: shortText, longText, dropdown, radio, checkboxSelect
forms.scope
string
obbligatorio
Possible values: number, organization, channel
forms.status
string
obbligatorio
Possible values: draft, active, deactivated
forms.updatedAt
string
obbligatorio
formOptions
object
formId
string
formEntryId
string
formEntry
object
Mostra attributi secondari
formEntry.answers
array of object
obbligatorio
Mostra attributi secondari
formEntry.answers.isDefault
boolean
formEntry.answers.key
string
obbligatorio
formEntry.answers.valueString
string
obbligatorio
formEntry.businessProfileId
string
The ID of an existing Business Profile.
formEntry.businessProfileVersion
integer
The version of the Business Profile.
formEntry.createdAt
string
obbligatorio
formEntry.displayName
string
formEntry.formId
string
obbligatorio
formEntry.id
string
obbligatorio
formEntry.locale
string
obbligatorio
formEntry.organizationId
string
obbligatorio
formEntry.reviewComment
string
formEntry.status
string
obbligatorio
The status of the form entry.
Possible values: draft, submitted, approved, rejected, expired
formEntry.tags
array of object
Mostra attributi secondari
formEntry.tags.key
string
obbligatorio
formEntry.tags.value
string
obbligatorio
formEntry.updatedAt
string
obbligatorio
Esempio di codice
curl -X PUT 'https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/compliance-requirements/{requirementName}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Example request
Get formEntryId from kyc-forms
Esempio di codice
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
Esempio di codice
PUT https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/compliance-requirements/brand:au
workspaceId string required
endpointId string required
Esempio di codice
{
    "formEntryId":"{formEntryId}",
    "formId":"4d74e9c0-3f3b-4d5f-8983-b343ecac3986",
    "type":"kyc-form"
}