DocumentatieEngagement 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
Queryparameters
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
Antwoord-payload
nextPageToken
string
The token to fetch the next page of results. If empty, there are no more results to fetch.
results
array of object
verplicht
Onderliggende attributen tonen
results.conditions
object
results.countryCode
string
results.createdAt
string
verplicht
results.defaultLocale
string
verplicht
results.gracePeriodDays
integer
results.id
string
verplicht
results.name
string
verplicht
results.questions
array of object
verplicht
Onderliggende attributen tonen
results.questions.locale
string
verplicht
results.questions.questions
array of object
verplicht
Onderliggende attributen tonen
results.questions.questions.conditions
array of object
Onderliggende attributen tonen
results.questions.questions.conditions.key
string
results.questions.questions.conditions.value
string
results.questions.questions.description
string
results.questions.questions.displayName
string
verplicht
results.questions.questions.format
string
verplicht
Possible values: none
results.questions.questions.key
string
verplicht
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
Onderliggende attributen tonen
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
verplicht
Possible values: bool, boolArray, intArray, float, floatArray
results.questions.questions.formQuestionConfig
object
Onderliggende attributen tonen
results.questions.questions.formQuestionConfig.stringDatetimeConfig
object
Onderliggende attributen tonen
results.questions.questions.formQuestionConfig.stringDatetimeConfig.allowTimezoneSelectionByUser
boolean
results.questions.questions.formQuestionConfig.stringDatetimeConfig.datetimeRange
object
verplicht
Onderliggende attributen tonen
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
verplicht
Possible values: number, organization, channel
results.status
string
verplicht
Possible values: draft, active, deactivated
results.updatedAt
string
verplicht
Codevoorbeeld
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.
Verzoek-payload
key
string
verplicht
The question key to upload the file for.
Antwoord-payload
url
string
verplicht
URL to post the image to
formData
object
verplicht
expectedFields
array of string
Codevoorbeeld
curl -X POST 'https://api.bird.com/organizations/{organizationId}/kyc-forms/{kycFormId}/files' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Example request
Codevoorbeeld
POST https://api.bird.com/organizations/{organizationId}/kyc-forms/4d74e9c0-3f3b-4d5f-8983-b343ecac3986/files
Example body request
Codevoorbeeld
{
    "key":"proofOfAddress"
}

3- Upload proof of Address image

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