Identities

The following endpoints are used to insert and retrieve entries representing identities from the database.

The identity object

The identity object represents the identity of an individual (or company) in the database.

Identity entity model

NameTypeDescriptionConstraints

address

Object

Address information.

Not Null

appId

String

Application ID. Format: uuid.

Not Null

birthday

String

Identity birthday. Format: Date.

Between 18 and 99 years

blocked

Boolean

Identity blocked status.

Not Null

createdAt

DateTime

Identity created at date.

Not Null

email

String

Identity email. Format: email

Not Null

gender

String

Identity gender.

[male, female, undefined]

id

String

Identity identifier. Format: uuid.

Not Null

identityConfirmed

Boolean

Identity with info confirmed.

Not Null

identityOwner

String

Identity company owner. Format: uuid.

Nullable

name

String

Identity name.

Not Null

phone

Object

Identity phone information.

Not Null

tax

Object

Identity tax information.

Not Null

type

String

Identity type.

[person, company]

kycStatus

Array

Identity kyc information.

updatedAt

DateTime

Identity updated at date.

Not Null

Address information

NameTypeDescriptionConstraints

city

String

Address city.

Not Null

country

String

Address country code.

Not Null

postalCode

String

Address postalCode.

Not Null

state

String

Address state.

Required when country is US

street

String

Address street.

Not Null

Phone information

NameTypeDescriptionConstraints

number

String

Phone number.

Not Null

sms

Boolean

Available for sms.

Not Null

Tax information

NameTypeDescriptionConstraints

country

String

Tax country code.

Not Null

idNumber

String

Tax id number.

Not Null

state

String

Tax state.

Required when country is US

formationRegion

String

Company formation region.

Required when identity type is company

Create an identity

POST /identities

POST [ENVIRONMENT HOSTNAME]/identities

This endpoint allows you to create a new identity.

Request Parameters

None

Body parameters

NameTypeDescriptionConstraintsRequired

address

Object

Address information.

Not null

true

birthday

String

Identity birthday. Format: Date.

Between 18 and 99 years

Required if type is person

documents

Array

Identity documents.

Not null

faceImages

Array[String]

Identity face images. Format: uri

Not null

email

String

Identity email. Format: email

Not null

true

gender

String

Identity gender

[Male, Female, Undefined]

Required if type is person

identityOwner

String

Identity company owner. Format: uuid.

Required if type is company

name

String

Identity name.

Not null

Required

phone

Object

Identity phone information.

Not null

Required

tax

Object

Identity tax information.

Not null

Required

type

String

Identity type.

Not null

[person, company]

Body address parameters

NameTypeDescriptionConstraintsRequired

city

String

Address city.

Not null

true

country

String

Address country.

Not null

true

postalCode

String

Address postal code

Not null

true

state

String

Address state

Not null

Required if country is US

street

String

Address street.

Not null

Required

Body documents parameters

NameTypeDescriptionConstraintsRequired

description

String

Document description.

label

String

Document label.

side

String

Document side.

[FrontSide, BackSide]

true

type

String

Document type

[DriverLicense,IdentityCard,Other,Passport,ResidencePermit,UtilityBill]

true

url

String

DocumentUrl. Format: uri

Not null

true

Body phone parameters

NameTypeDescriptionConstraintsRequired

number

String

Phone number.

Not null

sms

String

Available for sms.

Body tax parameters

NameTypeDescriptionConstraintsRequired

country

String

Tax country code.

Not null

true

idNumber

String

Tax id number.

Not null

true

state

String

Tax state.

Not null

Required if country is US

formationRegion

String

Company formation region.

Not null

Required if type is company

Response Options

400 Bad Request

  • validation_failed

    • If the required parameters are not provided.

    • If additional parameters are provided.

    • If some of the parameters type is invalid.

    • If some of the parameters constraints is not respected.

  • email_already_in_use

404 Not Found

  • identity_owner_not_found

    • If a non existent identity owner id is provided.

422 Unprocessable entity

  • identity_owner_must_be_of_type_person

    • If identity owner is not of type person.

200 OK

Example Call

POST [ENVIRONMENT HOSTNAME]/identities

{
  "address": {
    "city": "Braga",
    "country": "PT",
    "postalCode": "4444-333",
    "state": "Braga",
    "street": "Avenida D. João I,  40"
  },
  "birthday": "2000-11-11",
  "email": "foobar@publicmint.com",
  "gender": "Male",
  "name": "João Pedro Soares",
  "phone": {
    "number": "910000000",
    "sms": false
  },
  "tax": {
    "country": "PT",
    "idNumber": "1111111111",
    "state": "Braga"
  },
  "type": "person",
  "documents": [{
    "description": "ID card",
    "label": "id card",
    "side": "FrontSide",
    "type": "IdentityCard",
    "url": "https://[pmint_aws_s3_bucket].s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
  }],
  "faceImages": ["https://[pmint_aws_s3_bucket].s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"]
}

On the Sandbox environment, you can use the approve KYC endpoint to simulate and approve or reject the identity you created.

Get an identity

GET /identities/:id

GET [ENVIRONMENT HOSTNAME]/identities/:id

This endpoint retrieves and returns an identity owned by you from the database.

Request Parameters

Path parameters

NameTypeDescriptionConstraintsRequired

id

String

Identity identifier. Format: uuid.

true

Example Call

GET [ENVIRONMENT HOSTNAME]/identities/38882f21-ce8f-4e18-8b83-e43e082912ef

Get identities

GET /identities

GET [ENVIRONMENT HOSTNAME]/identities

This endpoint returns a paginated list of all identities owned by you.

Available filters

NameTypeExample

appId

default

filter[appId]=foobar

blocked

default

filter[blocked]=true

email

default,like

filter[email]=like:@publicmint.com

id

id, default

filter[id]=in:foobar

identityOwner

in,default

filter[identityOwner]=biz

name

default

filter[name]=fred

riskRating

in,nin,default

filter[riskRating]=nin:foo,bar

type

default

filter[type]=person

Available sorts

NameExample

createdAt

sort=createdAt sort=-createdAt

updatedAt

sort=updatedAt sort=-updatedAt

Paginate options

NameDescriptionExample

size

Defines the number of results per page. Default = 30.

page[size]=2

number

Defines the number of the page to retrieve. Default = 1

page[number]=2

all

Return all identities without pagination

all=true

Response Options

200 OK

Example Call

GET [ENVIRONMENT HOSTNAME]/identities

// PAGINATED

GET [ENVIRONMENT HOSTNAME]/identities?page[number]=1&page[size]=1

Get identity document presign url

Returns a presign url to view a specific identity document.

GET /identities/:identityId/documents/:id/presign-url

GET [ENVIRONMENT HOSTNAME]identities/:identityId/documents/:id/presign-url

This endpoint returns a paginated list of all identities owned by you.Available filtersAvailable sorts

Path parameters

NameTypeDescriptionConstraintsRequired

identityId

String

Identity identifier. Format: uuid.

true

id

String

Document identifier.Format: uuid.

true

Response Options

200 OK

Example Call

GET [ENVIRONMENT HOSTNAME]/identities/:identityId/documents/:id/presign-url

Update an identity

PATCH /identities/:id

PATCH [ENVIRONMENT_HOSTNAME]/identities/:id

Updates the identity information.

Path parameters

NameTypeDescriptionConstraintsRequired

id

String

Identity identifier. Format: uuid.

true

Request Parameters

Body parameters

NameTypeDescriptionConstraintsRequired

address

Object

Address information.

Not null

birthday

String

Identity birthday. Format: Date.

Between 18 and 99 years

documents

Array

Identity documents.

Not null

email

String

Identity email. Format: email

Not null

faceImages

Array[String]

Identity face images. Format: uri

Not null

gender

String

Identity gender

[Male, Female, Undefined]

identityOwner

String

Identity company owner. Format: uuid.

name

String

Identity name.

Not null

phone

Object

Identity phone information.

Not null

tax

Object

Identity tax information.

Not null

type

String

Identity type.

Not null

Note: Fields name, birthday, gender, tax.country and tax.idNumber can't be updated if identity is already confirmed (identityConfirmed = true)

Body address parameters

NameTypeDescriptionConstraintsRequired

city

String

Address city.

Not null

true

country

String

Address country.

Not null

true

postalCode

String

Address postal code

Not null

true

state

String

Address state

Not null

Required if country is US

street

String

Address street.

Not null

Required

Body documents parameters

NameTypeDescriptionConstraintsRequired

description

String

Document description.

label

String

Document label.

side

String

Document side.

[FrontSide, BackSide]

true

type

String

Document type

[DriverLicense,IdentityCard,Other,Passport,ResidencePermit,UtilityBill]

true

url

String

DocumentUrl. Format: uri

Not null

true

Body phone parameters

NameTypeDescriptionConstraintsRequired

number

String

Phone number.

Not null

sms

String

Available for sms.

Body tax parameters

NameTypeDescriptionConstraintsRequired

country

String

Tax country code.

Not null

true

idNumber

String

Tax id number.

Not null

true

state

String

Tax state.

Not null

Required if country is US

formationRegion

String

Company formation region.

Not null

Required if type is company

Response Options

400 Bad Request

  • validation_failed

    • If the required parameters are not provided.

    • If additional parameters are provided.

    • If some of the parameters type is invalid.

    • If some of the parameters constraints is not respected.

  • email_already_in_use

404 Not Found

  • identity_owner_not_found

    • If a non existent identity owner id is provided.

422 Unprocessable entity

  • identity_owner_must_be_of_type_person

    • If identity owner is not of type person.

200 OK

Example Call

PATCH [ENVIRONMENT HOSTNAME]/identities/38882f21-ce8f-4e18-8b83-e43e082912ef

{
  "address": {
    "city": "Braga",
    "country": "PT",
    "postalCode": "4444-333",
    "state": "Braga",
    "street": "Avenida D. João I,  40"
  },
  "birthday": "2000-11-11",
  "email": "foobar@publicmint.com",
  "gender": "Male",
  "name": "João Pedro Soares",
  "phone": {
    "number": "910000000",
    "sms": false
  },
  "tax": {
    "country": "PT",
    "idNumber": "1111111111",
    "state": "Braga"
  },
  "documents": [{
    "description": "ID card",
    "label": "id card",
    "side": "FrontSide",
    "type": "IdentityCard",
    "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
  }],
  "faceImages": ["https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"]
}js

Get operations

GET /identities/:id/operations

Returns a list of all enabled operations for the active KYC providers and the current status of each one, depending on the KYC status of the identity.

Request Parameters

Path parameters

NameTypeDescriptionConstraintsRequired

id

String

Identity identifier. Format: uuid.

true

Response Options

200 OK

Request example:

GET <hostname>/identities/e7941059-74c6-4b3f-b029-d3aa03d1ea44/operation

Response example:

{
  "data": [{
    "action": "create",
    "active": false,
    "code": "deposit:wire",
    "reason": "kyc_required_status_not_reached"
  }, {
    "action": "create",
    "active": true,
    "code": "deposit:stablecoin"
  }, {
    "action": "create",
    "active": false,
    "code": "withdrawal:wire",
    "reason": "operation_not_active_due_to_extra_kyc_missing"
  }, {
    "action": "confirm",
    "active": false,
    "code": "withdrawal:stablecoin",
    "reason": "identity_kyc_is_missing"
  }]
}

Delete an identity

DELETE /identities/:id

DELETE [ENVIRONMENT_HOSTNAME]/identities/:id

Deletes the identity with the given Id.

Path parameters

NameTypeDescriptionConstraintsRequired

id

String

Identity identifier. Format: uuid.

true

Response Options

400 Bad Request

  • validation_failed

    • If an invalid identity id is provided.

404 Not Found

  • identity_not_found

    • If a non existent identity id is provided.

204 OK

Example Call

DELETE [ENVIRONMENT HOSTNAME]/identities/38882f21-ce8f-4e18-8b83-e43e082912ef

Last updated