Identities

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

• Create identity

• Get an identity

• Get an identity document presign url

• Get identities

• Update an identity

• Delete an identity

• Get operations

The identity object

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

Identity entity model

Name	Type	Description	Constraints
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

Name	Type	Description	Constraints
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

Name	Type	Description	Constraints
number	String	Phone number.	Not Null
sms	Boolean	Available for sms.	Not Null

Tax information

Name	Type	Description	Constraints
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

Name	Type	Description	Constraints	Required
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

Name	Type	Description	Constraints	Required
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

Name	Type	Description	Constraints	Required
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

Name	Type	Description	Constraints	Required
number	String	Phone number.	Not null
sms	String	Available for sms.

Body tax parameters

Name	Type	Description	Constraints	Required
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

Request

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": "[email protected]",
  "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"]
}

CURL

Response

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

Name	Type	Description	Constraints	Required
id	String	Identity identifier. Format: uuid.		true

Example Call

Request

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

CURL

Response

Get identities

GET /identities

GET [ENVIRONMENT HOSTNAME]/identities

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

Available filters

Name	Type	Example
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

Name	Example
createdAt	sort=createdAt sort=-createdAt
updatedAt	sort=updatedAt sort=-updatedAt

Paginate options

Name	Description	Example
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

Request

GET [ENVIRONMENT HOSTNAME]/identities

// PAGINATED

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

CURL

Response

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

Name	Type	Description	Constraints	Required
identityId	String	Identity identifier. Format: uuid.		true
id	String	Document identifier.Format: uuid.		true

Response Options

200 OK

Example Call

Request

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

CURL

Response

Update an identity

PATCH /identities/:id

PATCH [ENVIRONMENT_HOSTNAME]/identities/:id

Updates the identity information.

Path parameters

Name	Type	Description	Constraints	Required
id	String	Identity identifier. Format: uuid.		true

Request Parameters

Body parameters

Name	Type	Description	Constraints	Required
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

Name	Type	Description	Constraints	Required
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

Name	Type	Description	Constraints	Required
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

Name	Type	Description	Constraints	Required
number	String	Phone number.	Not null
sms	String	Available for sms.

Body tax parameters

Name	Type	Description	Constraints	Required
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

Request

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": "[email protected]",
  "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

CURL

Response

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

Name	Type	Description	Constraints	Required
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

Name	Type	Description	Constraints	Required
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

Request

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

CURL