Entity
An entity represents stored details for an entity like people, businesses and organisations. Using these endpoints allows for the creation and use of an entity_token that you can use in your requests.
info
- Authentication required: These endpoints require authentication. To learn how to authenticate, see our authentication documentation.
- Sample requests & responses: To test these endpoints with sample requests, use our Postman collection
- Swagger file: To view definitions for these endpoints, see our swagger file
POST Entity Token
This endpoint securely stores details for people, businesses and organizations, and returns an entity_token that you can use anywhere entity details is required.
Endpoint:
/entity_token
Sample Messages
Sample Request
{
"entity_type": "person",
"details_format": "details",
"entity_details": {
"name": {
"first": "Kevin",
"middle": "",
"last": "Roger",
"suffix": "",
"prefix": ""
},
"addresses": [
{
"type": "billing",
"details": {
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"city": "Richardson",
"state_region_province": "TX",
"country": "US",
"your_address_reference": "string"
}
}
],
"email": "user@example.com",
"phone_number": {
"type": "mobile",
"details": {
"country_code": "IR",
"unformatted_number": "123456789",
"formatted_number": "333"
},
"your_phone_number_reference": "string"
}
}
}
Sample Response
{
"entity_id": "50161519-fc7c-48e6-8472-e01db44d8e3e",
"your_entity_reference": "",
"entity_type": "details",
"entity_details": {
"digital_addresses": [
{
"details": "user@example.com",
"type": "email"
}
],
"names": [
{
"details": "Kevin",
"type": "first_name"
},
{
"details": "Roger",
"type": "last_name"
}
],
"phone_numbers": [
{
"details": {
"country_code": "IR",
"formatted_number": "333",
"e164_number": "123456789"
},
"type": "mobile"
}
],
"physical_addresses": [
{
"details": {
"city": "Richardson",
"country": "US",
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"state_region_province": "TX"
},
"type": "billing",
"your_physical_address_reference": "string"
}
]
}
}
GET Entity Token
Returns an entity token including details and status.
/entity_token
Sample Messages
Sample Response
{
"entity_id": "50161519-fc7c-48e6-8472-e01db44d8e3e",
"your_entity_reference": "",
"entity_type": "details",
"entity_details": {
"digital_addresses": [
{
"details": "user@example.com",
"type": "email"
}
],
"names": [
{
"details": "Kevin",
"type": "first_name"
},
{
"details": "Roger",
"type": "last_name"
}
],
"phone_numbers": [
{
"details": {
"country_code": "IR",
"formatted_number": "333",
"e164_number": "123456789"
},
"type": "mobile"
}
],
"physical_addresses": [
{
"details": {
"city": "Richardson",
"country": "US",
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"state_region_province": "TX"
},
"type": "billing",
"your_physical_address_reference": "string"
}
]
}
}
POST Entity Token
Securely updates details for an entity
/entity_token/{entity_token}
Sample Messages
Sample Request
{
"entity_type": "person",
"details_format": "details",
"entity_details": {
"name": {
"first": "NewFirstName",
"middle": "",
"last": "Roger",
"suffix": "",
"prefix": ""
},
"addresses": [
{
"type": "billing",
"details": {
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"city": "Richardson",
"state_region_province": "TX",
"country": "US",
"your_address_reference": "string"
}
}
],
"email": "user@example.com",
"phone_number": {
"type": "mobile",
"details": {
"country_code": "IR",
"unformatted_number": "123456789",
"formatted_number": "333"
},
"your_phone_number_reference": "string"
}
}
}
Sample Response
{
"entity_id": "6ef9c24e-55ce-4212-8112-bf410c0e0d04",
"your_entity_reference": "",
"entity_type": "details",
"entity_details": {
"digital_addresses": [
{
"details": "user@example.com",
"type": "email"
}
],
"names": [
{
"details": "NewFirstName",
"type": "first_name"
},
{
"details": "Roger",
"type": "last_name"
}
],
"phone_numbers": [
{
"details": {
"country_code": "IR",
"formatted_number": "333",
"e164_number": "123456789"
},
"type": "mobile"
}
],
"physical_addresses": [
{
"details": {
"city": "Richardson",
"country": "US",
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"state_region_province": "TX"
},
"type": "billing",
"your_physical_address_reference": "string"
}
]
}
}
HTTP Response Codes
Below is a table summarizing the various HTTP response codes and their descriptions.
| HTTP Status Code | Response Schema | Description |
|---|---|---|
| 200 | Charge | The charge response provides the status of the most recent charge event and ledger balances and tokens for the payment, order, and settlement (if available). |
| 201 | Charge Pending | The pending charge response provides the pending status of the most recent charge event. |
| 202 | Charge Money Error | The money error charge response provides error information about the most recent charge event, which had a money error. Please review the error fields to determine how to resolve this error. |
| 203 | Charge Connectivity Error | The connector error charge response provides error information about the most recent charge event, which had a connector error. Please review the error fields to determine how to resolve this error. |
| 211 | Charge Data Error | The charge error response provides error information and the status of the charge as well as balances for the payment, order, and settlement (if available) ledgers. Also provided are the token references for the associated payment, order, session, and entity tokens. |
| 400 | Charge Request Error | The request error charge response provides error information about the most recent API request, which contained a schema error. Please review the error fields to determine how to resolve this error. |
| 500 | System Error | An error occurred either within /charge or externally in a system Connected to /charge. Please notify DataMesh via ecomm@datameshgroup.com. |