DocumentationEngagement 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
Paramètres de requête
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
Corps de la réponse
nextPageToken
string
The token to fetch the next page of results. If empty, there are no more results to fetch.
results
array of object
obligatoire
Afficher les attributs enfants
results.conditions
object
results.countryCode
string
results.createdAt
string
obligatoire
results.defaultLocale
string
obligatoire
results.gracePeriodDays
integer
results.id
string
obligatoire
results.name
string
obligatoire
results.questions
array of object
obligatoire
Afficher les attributs enfants
results.questions.locale
string
obligatoire
results.questions.questions
array of object
obligatoire
Afficher les attributs enfants
results.questions.questions.conditions
array of object
Afficher les attributs enfants
results.questions.questions.conditions.key
string
results.questions.questions.conditions.value
string
results.questions.questions.description
string
results.questions.questions.displayName
string
obligatoire
results.questions.questions.format
string
obligatoire
Possible values: none
results.questions.questions.key
string
obligatoire
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
Afficher les attributs enfants
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
obligatoire
Possible values: bool, boolArray, intArray, float, floatArray
results.questions.questions.formQuestionConfig
object
Afficher les attributs enfants
results.questions.questions.formQuestionConfig.stringDatetimeConfig
object
Afficher les attributs enfants
results.questions.questions.formQuestionConfig.stringDatetimeConfig.allowTimezoneSelectionByUser
boolean
results.questions.questions.formQuestionConfig.stringDatetimeConfig.datetimeRange
object
obligatoire
Afficher les attributs enfants
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
obligatoire
Possible values: number, organization, channel
results.status
string
obligatoire
Possible values: draft, active, deactivated
results.updatedAt
string
obligatoire
Exemple de code
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.
Corps de la requête
key
string
obligatoire
The question key to upload the file for.
Corps de la réponse
url
string
obligatoire
URL to post the image to
formData
object
obligatoire
expectedFields
array of string
Exemple de code
curl -X POST 'https://api.bird.com/organizations/{organizationId}/kyc-forms/{kycFormId}/files' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Example request
Exemple de code
POST https://api.bird.com/organizations/{organizationId}/kyc-forms/4d74e9c0-3f3b-4d5f-8983-b343ecac3986/files
Example body request
Exemple de code
{
    "key":"proofOfAddress"
}

3- Upload proof of Address image

Example request
Exemple de code
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
Corps de la requête
locale
string
obligatoire
answers
array of object
obligatoire
Afficher les paramètres enfants
answers.isDefault
boolean
answers.key
string
obligatoire
answers.valueString
string
obligatoire
status
string
The status of the form entry.
Possible values: draft, submitted, approved, rejected, expired
displayName
string
Corps de la réponse
answers
array of object
obligatoire
Afficher les attributs enfants
answers.isDefault
boolean
answers.key
string
obligatoire
answers.valueString
string
obligatoire
businessProfileId
string
The ID of an existing Business Profile.
businessProfileVersion
integer
The version of the Business Profile.
createdAt
string
obligatoire
displayName
string
formId
string
obligatoire
id
string
obligatoire
locale
string
obligatoire
organizationId
string
obligatoire
reviewComment
string
status
string
obligatoire
The status of the form entry.
Possible values: draft, submitted, approved, rejected, expired
tags
array of object
Afficher les attributs enfants
tags.key
string
obligatoire
tags.value
string
obligatoire
updatedAt
string
obligatoire
Exemple de code
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
Exemple de code
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
Exemple de code
{
  "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).
Corps de la requête
formId
string
formEntryId
string
type
string
obligatoire
Possible values: kyc-form
Corps de la réponse
status
string
obligatoire
Possible values: satisfied, pending, unsatisfied
mutable
boolean
obligatoire
immutableReason
string
Possible values: managed, dependency, none
message
string
evaluatedAt
string
issues
array of string
userId
string
name
string
obligatoire
type
string
obligatoire
Possible values: kyc-form
capabilities
array of string
obligatoire
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
Afficher les attributs enfants
forms.conditions
object
forms.countryCode
string
forms.createdAt
string
obligatoire
forms.defaultLocale
string
obligatoire
forms.gracePeriodDays
integer
forms.id
string
obligatoire
forms.name
string
obligatoire
forms.questions
array of object
obligatoire
Afficher les attributs enfants
forms.questions.locale
string
obligatoire
forms.questions.questions
array of object
obligatoire
Afficher les attributs enfants
forms.questions.questions.conditions
array of object
Afficher les attributs enfants
forms.questions.questions.conditions.key
string
forms.questions.questions.conditions.value
string
forms.questions.questions.description
string
forms.questions.questions.displayName
string
obligatoire
forms.questions.questions.format
string
obligatoire
Possible values: none
forms.questions.questions.key
string
obligatoire
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
Afficher les attributs enfants
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
obligatoire
Possible values: bool, boolArray, intArray, float, floatArray
forms.questions.questions.formQuestionConfig
object
Afficher les attributs enfants
forms.questions.questions.formQuestionConfig.stringDatetimeConfig
object
Afficher les attributs enfants
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.allowTimezoneSelectionByUser
boolean
forms.questions.questions.formQuestionConfig.stringDatetimeConfig.datetimeRange
object
obligatoire
Afficher les attributs enfants
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
obligatoire
Possible values: number, organization, channel
forms.status
string
obligatoire
Possible values: draft, active, deactivated
forms.updatedAt
string
obligatoire
formOptions
object
formId
string
formEntryId
string
formEntry
object
Afficher les attributs enfants
formEntry.answers
array of object
obligatoire
Afficher les attributs enfants
formEntry.answers.isDefault
boolean
formEntry.answers.key
string
obligatoire
formEntry.answers.valueString
string
obligatoire
formEntry.businessProfileId
string
The ID of an existing Business Profile.
formEntry.businessProfileVersion
integer
The version of the Business Profile.
formEntry.createdAt
string
obligatoire
formEntry.displayName
string
formEntry.formId
string
obligatoire
formEntry.id
string
obligatoire
formEntry.locale
string
obligatoire
formEntry.organizationId
string
obligatoire
formEntry.reviewComment
string
formEntry.status
string
obligatoire
The status of the form entry.
Possible values: draft, submitted, approved, rejected, expired
formEntry.tags
array of object
Afficher les attributs enfants
formEntry.tags.key
string
obligatoire
formEntry.tags.value
string
obligatoire
formEntry.updatedAt
string
obligatoire
Exemple de code
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
Exemple de code
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
Exemple de code
PUT https://api.bird.com/workspaces/{workspaceId}/endpoints/{endpointId}/compliance-requirements/brand:au
workspaceId string required
endpointId string required
Exemple de code
{
    "formEntryId":"{formEntryId}",
    "formId":"4d74e9c0-3f3b-4d5f-8983-b343ecac3986",
    "type":"kyc-form"
}