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
[ENVIRONMENT HOSTNAME]
/identities
POST /identities
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
CURL
Response
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 --location --request POST 'https://api.sandbox.publicmint.io/identities' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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-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"]
}
'
{
    "data": {
        "documents": [
            {
                "createdAt": "2022-03-31T13:08:52.049Z",
                "deletedAt": null,
                "description": "ID card",
                "id": "bfca84a4-3e52-4a7d-92da-b17c6a5e59ac",
                "identityId": "38882f21-ce8f-4e18-8b83-e43e082912ef",
                "label": "id card",
                "side": "frontSide",
                "type": "identityCard",
                "updatedAt": "2022-03-31T13:08:52.049Z",
                "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
            },
            {
                "createdAt": "2022-03-31T13:08:52.114Z",
                "deletedAt": null,
                "description": null,
                "id": "0b12e957-5643-4943-9eeb-6755c02721e0",
                "identityId": "38882f21-ce8f-4e18-8b83-e43e082912ef",
                "label": null,
                "side": "frontSide",
                "type": "faceImage",
                "updatedAt": "2022-03-31T13:08:52.114Z",
                "url": "https://pmint-custodial-api-sandbox-identity-docs.s3.amazonaws.com/fd/fc/09/dd/4nHVF9Hz9FArIrUo.jpeg"
            }
        ],
        "address": {
            "city": "Braga",
            "state": "Braga",
            "street": "Avenida D. João I,  40",
            "country": "PT",
            "postalCode": "4444-333"
        },
        "appId": "80937bc6-9578-45c8-b691-ea6b8a5d17e9",
        "birthday": "2000-11-11",
        "blocked": false,
        "createdAt": "2022-03-31T13:08:52.030Z",
        "email": "[email protected]",
        "gender": "Male",
        "id": "38882f21-ce8f-4e18-8b83-e43e082912ef",
        "identityConfirmed": false,
        "identityOwner": null,
        "name": "João Pedro Soares",
        "phone": {
            "sms": false,
            "number": "910000000"
        },
        "tax": {
            "state": "Braga",
            "country": "PT",
            "idNumber": "1111111111"
        },
        "type": "person",
        "updatedAt": "2022-03-31T13:08:52.030Z"
    }
}
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
[ENVIRONMENT HOSTNAME]
/identities/:id
GET /identities/:id
Request Parameters
Path parameters
Name
Type
Description
Constraints
Required
id
String
Identity identifier. Format: uuid.
​
true
Example Call
Request
CURL
Response
GET [ENVIRONMENT HOSTNAME]/identities/38882f21-ce8f-4e18-8b83-e43e082912ef
curl --location --request GET 'https://api.sandbox.publicmint.io/identities/38882f21-ce8f-4e18-8b83-e43e082912ef' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm'
{
    "data": {
        "address": {
            "city": "Braga",
            "state": "Braga",
            "street": "Avenida D. João I,  40",
            "country": "PT",
            "postalCode": "4444-333"
        },
        "appId": "80937bc6-9578-45c8-b691-ea6b8a5d17e9",
        "birthday": "2000-11-11",
        "blocked": false,
        "createdAt": "2022-03-31T13:08:52.030Z",
        "email": "[email protected]",
        "gender": "Male",
        "id": "38882f21-ce8f-4e18-8b83-e43e082912ef",
        "identityConfirmed": false,
        "identityOwner": null,
        "name": "João Pedro Soares",
        "phone": {
            "sms": false,
            "number": "910000000"
        },
        "tax": {
            "state": "Braga",
            "country": "PT",
            "idNumber": "1111111111"
        },
        "type": "person",
        "updatedAt": "2022-03-31T13:08:52.030Z"
    }
}
Get identities
get
[ENVIRONMENT HOSTNAME]
/identities
GET /identities
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
CURL
Response
GET [ENVIRONMENT HOSTNAME]/identities
​
// PAGINATED
​
GET [ENVIRONMENT HOSTNAME]/identities?page[number]=1&page[size]=1
curl --location --request GET 'https://api.sandbox.publicmint.io/identities' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm'
{
    "data": [
        {
            "address": {
                "city": "Braga",
                "state": "Braga",
                "street": "Avenida D. João I,  40",
                "country": "PT",
                "postalCode": "4444-333"
            },
            "appId": "80937bc6-9578-45c8-b691-ea6b8a5d17e9",
            "birthday": "2000-11-11",
            "blocked": false,
            "createdAt": "2022-03-31T13:08:52.030Z",
            "email": "[email protected]",
            "gender": "Male",
            "id": "38882f21-ce8f-4e18-8b83-e43e082912ef",
            "identityConfirmed": false,
            "identityOwner": null,
            "name": "João Pedro Soares",
            "phone": {
                "sms": false,
                "number": "910000000"
            },
            "tax": {
                "state": "Braga",
                "country": "PT",
                "idNumber": "1111111111"
            },
            "type": "person",
            "updatedAt": "2022-03-31T13:08:52.030Z"
        }
    ],
    "total": 1
}
Get identity document presign url
Returns a presign url to view a specific identity document.
get
[ENVIRONMENT HOSTNAME]
identities/:identityId/documents/:id/presign-url
GET /identities/:identityId/documents/:id/presign-url
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
CURL
Response
GET [ENVIRONMENT HOSTNAME]/identities/:identityId/documents/:id/presign-url
​
curl --location --request GET 'https://api.sandbox.publicmint.io/identities/38882f21-ce8f-4e18-8b83-e43e082912ef/documents/2fe368e4-38ea-4329-bd2c-f8785d92ee57/presign-url' \
--header 'apiKey: dfQ0ouwt0R14TPd2wxBzKtslWrBN5zfm'
{
    "data": {
        "presignUrl": "https://ik.imagekit.io/p7reuy1mvbpd/aws-prod/2021/11/06/12/1c05077d-ad00-49c0-94de-4323ed8f9ad5/rn_image_picker_lib_temp_239e3a8b-6129-4d14-8fe7-ed9565cfc204.jpg"
    }
}
​
Update an identity
patch
[ENVIRONMENT_HOSTNAME]
/identities/:id
PATCH /identities/:id
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

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`

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]`

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`

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`

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

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`

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`

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

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`

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