Participants

Participants are the organizations and people that own documents and appear in events. Register them here to obtain the participantId and addressId values referenced when creating a document.

All read operations are scoped to the caller's credential: records your credential created return every field, while records belonging to other participants return only identification and location fields, with the street masked.

Participants

Create participant

curl -X POST "https://example.com/participants" \  -H "Authorization: string" \  -H "Content-Type: application/json" \  -d '{    "countryCode": "BR",    "name": "João da Fonseca",    "taxId": "11111111111",    "taxIdType": "CPF",    "type": "COMPANY"  }'

{  "id": "28b04f62-8fe2-4332-b854-fe8a922788b5"}

Use POST /participants to register a participant in your credential's dataset. The response returns the generated participantId.

Get participant by key

curl -X GET "https://example.com/participants?countryCode=BR&taxId=11111111111&taxIdType=CPF" \  -H "Authorization: string"

{  "businessName": "Empresa Exemplo LTDA",  "countryCode": "BR",  "email": "contato@exemplo.com.br",  "id": "28b04f62-8fe2-4332-b854-fe8a922788b5",  "mobileNumber": "+5511987654321",  "name": "Fulano de Tal",  "taxId": "11222333000144",  "taxIdType": "CPF",  "telephoneNumber": "+551133224455",  "type": "COMPANY"}

Use GET /participants to look up a participant by its natural key — country code, document type, and document number. The document number (taxId) is passed in the query string.

Get participant by id

curl -X GET "https://example.com/participants/string" \  -H "Authorization: string"

{  "businessName": "Empresa Exemplo LTDA",  "countryCode": "BR",  "email": "contato@exemplo.com.br",  "id": "28b04f62-8fe2-4332-b854-fe8a922788b5",  "mobileNumber": "+5511987654321",  "name": "Fulano de Tal",  "taxId": "11222333000144",  "taxIdType": "CPF",  "telephoneNumber": "+551133224455",  "type": "COMPANY"}

Use GET /participants/{id} to fetch a participant by its Carrot identifier.

Addresses

Addresses belong to a participant, so every address operation is scoped to a participantId.

Create address

curl -X POST "https://example.com/participants/string/addresses" \  -H "Authorization: string" \  -H "Content-Type: application/json" \  -d '{    "city": "São Paulo",    "countryCode": "BR",    "countryState": "São Paulo",    "name": "Edifício Jardins de Monet",    "number": "500",    "street": "Rua das Colinas"  }'

{  "id": "28b04f62-8fe2-4332-b854-fe8a922788b5"}

Use POST /participants/{participantId}/addresses to add an address to a participant. The response returns the generated addressId, which can then be referenced as addressId when creating a document.

List participant addresses

curl -X GET "https://example.com/participants/string/addresses" \  -H "Authorization: string"

[  {    "city": "São Paulo",    "complement": "Apto. 12",    "countryCode": "BR",    "countryState": "São Paulo",    "id": "28b04f62-8fe2-4332-b854-fe8a922788b5",    "latitude": -23.5505,    "longitude": -46.6333,    "neighborhood": "Jardins",    "number": "245",    "participantId": "28b04f62-8fe2-4332-b854-fe8a922788b5",    "street": "Rua das Colinas",    "zipCode": "01310100"  }]

Use GET /participants/{participantId}/addresses to list a participant's addresses. Addresses your credential did not create are returned with identification and location fields only and the street masked.

For the end-to-end onboarding sequence, see Integrations Quick Start.