Bridge Associated Persons API
The Associated Persons API from Bridge — 1 operation(s) for associated persons.
OpenAPI Specification
openapi: 3.0.2
info:
title: Bridge API Keys Associated Persons API
description: APIs to move into, out of, and between any form of a dollar
version: '1'
servers:
- url: https://api.bridge.xyz/v0
description: The base path for all resources
security:
- ApiKey: []
tags:
- name: Associated Persons
paths:
/associated_persons/{associatedPersonID}:
parameters:
- $ref: '#/components/parameters/AssociatedPersonIDParameter'
get:
summary: Get a single associated person
tags:
- Associated Persons
description: Retrieve an associated person by ID
responses:
'200':
description: Successful associated person response
content:
application/json:
schema:
$ref: '#/components/schemas/AssociatedPersonResponse'
examples:
SuccessfulAssociatedPersonResponse:
$ref: '#/components/examples/SuccessfulAssociatedPersonResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
put:
summary: Update a single associated person
tags:
- Associated Persons
requestBody:
description: Associated person data to update
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AssociatedPerson'
responses:
'200':
description: Updated associated person
content:
application/json:
schema:
$ref: '#/components/schemas/AssociatedPersonResponse'
examples:
SuccessfulAssociatedPersonResponse:
$ref: '#/components/examples/SuccessfulAssociatedPersonResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
delete:
summary: Delete a single associated person
tags:
- Associated Persons
description: Delete an associated person by ID
responses:
'200':
description: Successfully deleted associated person
content:
application/json:
schema:
$ref: '#/components/schemas/AssociatedPersonResponse'
examples:
SuccessfulAssociatedPersonResponse:
$ref: '#/components/examples/SuccessfulAssociatedPersonResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
components:
responses:
AuthenticationError:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MissingTokenError:
summary: No Api-Key header
description: The header may be missing or misspelled.
value:
code: required
location: header
name: Api-Key
message: Missing Api-Key header
InvalidTokenError:
summary: Invalid key in Api-Key header
value:
code: invalid
location: header
name: Api-Key
message: Invalid Api-Key header
NotFoundError:
description: No resource found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
NotFoundErrorExample:
summary: Invalid customer id
value:
code: Invalid
message: Unknown customer id
BadRequestError:
description: Request containing missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
BadCustomerRequestErrorExample:
summary: Bad customer request
value:
code: bad_customer_request
message: fields missing from customer body.
name: first_name,ssn
UnexpectedError:
description: Unexpected error. User may try and send the request again.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnexpectedError:
summary: An unexpected error
value:
errors:
- code: unexpected
message: An expected error occurred, you may try again later
schemas:
Error:
required:
- code
- message
properties:
code:
type: string
minLength: 1
maxLength: 256
message:
type: string
minLength: 1
maxLength: 512
source:
title: ErrorSource
required:
- location
- key
properties:
location:
type: string
enum:
- path
- query
- body
- header
key:
type: string
description: Comma separated names of the properties or parameters causing the error
Id:
description: A UUID that uniquely identifies a resource
type: string
pattern: '[a-z0-9]*'
minLength: 1
maxLength: 42
AssociatedPerson:
required:
- first_name
- last_name
- email
- residential_address
- identifying_information
- birth_date
- has_ownership
- has_control
- is_signer
properties:
first_name:
type: string
minLength: 1
maxLength: 1024
description: The first name of the associated person
middle_name:
type: string
minLength: 1
maxLength: 1024
description: The middle name of the associated person
last_name:
type: string
minLength: 2
maxLength: 1024
description: The last name of the associated person
transliterated_first_name:
type: string
description: 'Required when the `first_name` includes any non Latin-1 characters. Acceptable characters - Latin-1 Unicode Character Range: À-ÖØ-ßà-öø-ÿ; Standard Unicode Character Range: -~'
minLength: 1
maxLength: 256
transliterated_middle_name:
type: string
description: 'Required when the `middle_name` includes any non Latin-1 characters. Acceptable characters - Latin-1 Unicode Character Range: À-ÖØ-ßà-öø-ÿ; Standard Unicode Character Range: -~'
minLength: 1
maxLength: 256
transliterated_last_name:
type: string
description: 'Required when the `last_name` includes any non Latin-1 characters. Acceptable characters - Latin-1 Unicode Character Range: À-ÖØ-ßà-öø-ÿ; Standard Unicode Character Range: -~'
minLength: 1
maxLength: 256
email:
type: string
minLength: 1
maxLength: 1024
description: The persons primary email address
phone:
description: The persons phone in format "+12223334444"
type: string
minLength: 1
maxLength: 1024
residential_address:
writeOnly: true
$ref: '#/components/schemas/Address2025WinterRefresh'
description: The residential address of the associated person. This must be a physical address and cannot be a PO Box.
transliterated_residential_address:
writeOnly: true
$ref: '#/components/schemas/Address2025WinterRefresh'
description: 'Required when any part of the `residential_address` includes any non Latin-1 characters. Acceptable characters - Latin-1 Unicode Character Range: À-ÖØ-ßà-öø-ÿ; Standard Unicode Character Range: -~'
birth_date:
type: string
description: Date of birth in format yyyy-mm-dd. Must be at least 18 years old.
minLength: 10
maxLength: 10
nationality:
type: string
writeOnly: true
description: 'Legacy single nationality (ISO 3166-1 alpha-3). Prefer `nationalities` for all nationalities. See individual customer `nationality` / `nationalities` and [EEA nationalities](https://apidocs.bridge.xyz/platform/customers/customers/eea-updated-requirements#nationalities).
'
nationalities:
type: array
writeOnly: true
description: 'All nationalities for this associated person (ISO 3166-1 alpha-3). **EEA / BBSA in-scope businesses:** required on each UBO / associated person where policy applies.
'
items:
type: string
minLength: 3
maxLength: 3
place_of_birth:
writeOnly: true
$ref: '#/components/schemas/PlaceOfBirthInput'
verified_database_at:
type: string
format: date-time
writeOnly: true
description: 'Write-only ISO 8601 timestamp. For **EEA in-scope** associated persons on **reliance**, second factor with `verified_govid_at` under `TWO_FORMS_OF_ID_RELIANCE`.
'
has_ownership:
type: boolean
description: True if this person has at least 25% ownership of the business.
has_control:
type: boolean
description: 'True if this is the control person of the company, having significant responsibility to control, manage or influence the activities of the business entity. At least one control person must be specified. '
is_signer:
type: boolean
description: True if this person is able to authorize transactions on behalf of the business. At least one signer must be specified.
is_director:
type: boolean
description: True if this person is an appointed director of the company. **EEA / BBSA in-scope businesses:** must be set for every associated person (complete director list). See [EEA updated requirements](https://apidocs.bridge.xyz/platform/customers/customers/eea-updated-requirements#complete-director-list).
title:
type: string
description: The title of this associated person at the company, e.g. CEO, CFO, etc. Required if has_control is true.
minLength: 1
maxLength: 1024
ownership_percentage:
type: integer
description: 'Ultimate ownership percentage of the business. **EEA / BBSA in-scope businesses:** required when `has_ownership` is true for UBOs at or above the configured threshold (default 25%). See [EEA updated requirements](https://apidocs.bridge.xyz/platform/customers/customers/eea-updated-requirements#ownership-percentage-per-ubo).
'
writeOnly: true
attested_ownership_structure_at:
type: string
description: The date or timestamp when this individual attested to the correctness of the ownership structure provided to Bridge. If provided by at least one control person, ownership documents for the business are not required.
writeOnly: true
verified_account_authorization_at:
type: string
format: date-time
description: 'Write-only ISO 8601 timestamp. For **EEA in-scope** businesses on **reliance**, may satisfy signatory authority for signers who are not owner, director, or control person (`signature_authority_requirement(for_reliance: true)`); alternative is `documents` with purpose `proof_of_signatory_authority`. See [EEA updated requirements — LOA](https://apidocs.bridge.xyz/platform/customers/customers/eea-updated-requirements#letter-of-authority-loa).
'
writeOnly: true
relationship_established_at:
type: string
description: The date or timestamp when the associated person relationship was established in format yyyy-mm-dd.
verified_govid_at:
type: string
format: date-time
description: 'Write-only ISO 8601 timestamp. For **EEA in-scope** associated persons on **reliance**, use with `verified_selfie_at` or `verified_database_at` under `TWO_FORMS_OF_ID_RELIANCE`.
'
writeOnly: true
verified_selfie_at:
type: string
format: date-time
description: 'Write-only ISO 8601 timestamp. For **EEA in-scope** associated persons on **reliance**, pairs with `verified_govid_at` or `verified_database_at` under `TWO_FORMS_OF_ID_RELIANCE`.
'
writeOnly: true
identifying_information:
$ref: '#/components/schemas/IdentifyingInformation'
documents:
$ref: '#/components/schemas/IndividualDocuments'
AssociatedPersonResponse:
type: object
required:
- id
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the associated person
email:
type: string
description: The email address of the associated person
first_name:
type: string
minLength: 2
maxLength: 1024
description: The first name of the associated person
last_name:
type: string
minLength: 2
maxLength: 1024
description: The last name of the associated person
has_ownership:
type: boolean
description: True if this person has at least 25% ownership of the business.
has_control:
type: boolean
description: True if this is the control person of the company, having significant responsibility to control, manage or influence the activities of the business entity.
is_signer:
type: boolean
description: True if this person is able to authorize transactions on behalf of the business.
title:
type: string
description: The title of this associated person at the company, e.g. CEO, CFO, etc.
attested_ownership_structure_at:
type: string
description: When this individual attested to the correctness of the ownership structure provided to Bridge. If provided by at least one control person, ownership documents for the business are not required.
relationship_established_at:
type: string
description: When the associated person relationship was established in format yyyy-mm-dd.
created_at:
type: integer
description: Created timestamp in milliseconds since Unix epoch
updated_at:
type: integer
description: Last updated timestamp in milliseconds since Unix epoch
IndividualDocuments:
writeOnly: true
type: array
title: Documents
description: Please click "ADD OBJECT" for more information.
items:
type: object
required:
- purposes
- file
properties:
purposes:
type: array
items:
type: string
enum:
- proof_of_account_purpose
- proof_of_address
- proof_of_individual_name_change
- proof_of_relationship
- proof_of_source_of_funds
- proof_of_source_of_wealth
- proof_of_tax_identification
- other
description: A list of purposes that the given document serves. Click "ADD STRING" to see common document purposes for individuals, or view the full list of possible values [here](https://apidocs.bridge.xyz/docs/supported-documents).
file:
type: string
description: "Base64 encoded image* of the provided document, following the data-uri scheme i.e. data:image/[type];base64,[base_64_encoded_file_contents], with a minimum size of 200px x 200px \n\n*Maximum File Size: 24MB\n\n*Valid file types: .pdf, .jpeg, .jpg, .png, .heic, .tif"
description:
type: string
description: A description describing the provided document. This field is required when `other` is provided as one of the purposes.
PlaceOfBirthInput:
type: object
description: 'Country (and optionally city) of birth. **EEA / BBSA in-scope customers:** supply when onboarding individuals or associated persons under the [EEA updated requirements](https://apidocs.bridge.xyz/platform/customers/customers/eea-updated-requirements#country-of-birth-and-city-of-birth). This is a sparse address — no street address. At least `country` should be present when the object is sent; `city` is recommended and will be required by EU law in 2027.
'
properties:
country:
type: string
minLength: 3
maxLength: 3
description: ISO 3166-1 alpha-3 country code for the place of birth.
city:
type: string
minLength: 1
description: City of birth (recommended for EEA).
Address2025WinterRefresh:
required:
- street_line_1
- country
- city
properties:
street_line_1:
type: string
minLength: 4
street_line_2:
type: string
minLength: 1
city:
type: string
minLength: 1
subdivision:
type: string
description: ISO 3166-2 subdivision code. Must be supplied for US addresses.
minLength: 1
maxLength: 3
postal_code:
type: string
description: Must be supplied for countries that use postal codes.
minLength: 1
country:
description: Three-letter alpha-3 country code as defined in the ISO 3166-1 spec.
type: string
minLength: 3
maxLength: 3
IdentifyingInformation:
writeOnly: true
type: array
title: Identification Information
items:
type: object
required:
- issuing_country
- type
properties:
type:
type: string
description: 'Tax identification number type or government-issued ID document type (see enum). Country-specific tax and national ID lists: [Individuals](https://apidocs.bridge.xyz/docs/individual-tax-identification-numbers-by-country), [Businesses](https://apidocs.bridge.xyz/docs/business-tax-identification-numbers-by-country).
**EEA / BBSA (policy in `eea_requirements.rb`):** In-scope individuals and UBOs need **both** a valid national-ID-type entry and a valid TIN per [EEA updated requirements](https://apidocs.bridge.xyz/platform/customers/customers/eea-updated-requirements). In-scope businesses need business registration **and** business tax ID types per country tables there. **TIN issuing country** must match residence (individuals) or incorporation (businesses). **Foreign tax** outside the incorporation country: set `has_foreign_tax_registration` on the business customer and add TIN objects per jurisdiction ([foreign tax / tax residency](https://apidocs.bridge.xyz/platform/customers/customers/eea-updated-requirements#tax-residency-status-foreign-tax-registry)).
'
enum:
- drivers_license
- matriculate_id
- military_id
- national_id
- passport
- permanent_residency_id
- state_or_provincial_id
- visa
- abn
- acn
- ahv
- ak
- aom
- arbn
- avs
- bc
- bce
- bin
- bir
- bp
- brn
- bsn
- bvn
- cc
- cdi
- cedula_juridica
- cf
- cif
- cin
- cipc
- cn
- cnp
- cnpj
- cpf
- cpr
- crc
- crib
- crn
- cro
- cui
- cuil
- curp
- cuit
- cvr
- edrpou
- ein
- embg
- emirates_id
- en
- fin
- fn
- gstin
- gui
- hetu
- hkid
- hn
- ic
- ico
- id
- id_broj
- idno
- idnp
- idnr
- if
- iin
- ik
- inn
- ird
- itin
- itr
- iva
- jmbg
- kbo
- kvk
- matricule
- mf
- mn
- ms
- mst
- nic
- nicn
- nie
- nif
- nin
- nino
- nip
- nipc
- nipt
- nit
- npwp
- nric
- nrn
- nrt
- ntn
- nuit
- nzbn
- oib
- orgnr
- other
- pan
- partita_iva
- pesel
- pib
- pin
- pk
- ppsn
- qid
- rc
- regon
- rfc
- ricn
- rif
- rn
- rnc
- rnokpp
- rp
- rrn
- rtn
- ruc
- rut
- si
- sin
- siren
- siret
- spi
- ssm
- ssn
- steuer_id
- strn
- tckn
- tfn
- tin
- tpin
- trn
- ucn
- uen
- uic
- uid
- usc
- ust_idnr
- utr
- vat
- vkn
- voen
- y_tunnus
issuing_country:
type: string
description: The ISO 3166-1 (three-character) country code that issued the provided document.
number:
type: string
description: The unique identifier of the document. Required if this document is being used as a tax identification number (e.g., you are providing a passport or national_id with no other identification).
description:
type: string
description: A description describing the provided document. This field is required when `other` is selected.
expiration:
type: string
description: The expiration date of the given document in yyyy-mm-dd format.
image_front:
type: string
description: 'This field is optionally accepted for tax_id types, but required for government_id types. Base64 encoded image* of the front side of the provided document, following the data-uri scheme i.e. data:image/[type];base64,[base_64_encoded_file_contents], with a minimum size of 200px x 200px \n\n*Maximum File Size: 15MB\n\n*Valid file types: .pdf, .jpeg, .jpg, .png, .heic, .tif
_Note: When combined with an `image_back`, the combined size of both images must not exceed 24MB._
'
image_back:
type: string
description: 'Base64 encoded image* of the back side of the provided document, following the data-uri scheme i.e. data:image/[type];base64,[base_64_encoded_file_contents], with a minimum size of 200px x 200px \n\n*Maximum File Size: 15MB\n\n*Valid file types: .pdf, .jpeg, .jpg, .png, .heic, .tif
_Note: When combined with an `image_front`, the combined size of both images must not exceed 24MB._
'
parameters:
AssociatedPersonIDParameter:
name: associatedPersonID
in: path
description: Unique identifier for an associated person
required: true
schema:
$ref: '#/components/schemas/Id'
examples:
SuccessfulAssociatedPersonResponse:
summary: An associated person object
value:
id: associated_person_1234567890
email: associated_person@business.co
first_name: John
last_name: Smith
has_ownership: true
has_control: true
is_signer: true
title: Chief Executive Officer
relationship_established_at: '2025-05-27T17:55:33.308Z'
created_at: '2025-05-27T17:55:33.308Z'
updated_at: '2025-05-27T17:55:33.308Z'
securitySchemes:
ApiKey:
type: apiKey
name: Api-Key
in: header