Create a new entity | API

An entity is the individual you are seeking to verify through Credas. Within the API entities are identifiable by their entityId. 

Depending on your use case you may be advised to create an entity using this method or through a process.

Speak to your technical contact if you are unsure before proceeding with your integration.

Create a new entity

To create a new entity you must sent a POST request to the /api/v2/ci/entities endpoint. 

Request body

When sending your request to this endpoint you will need to provide some information on the entity, please refer to the example request body below.

{
    "emailAddress": "user@example.com",
    "phoneNumber": "07000000000",
    "firstName": "Test",
    "middleName": "Test",
    "surname": "Test",
    "reference": "Test",
    "userGroupId": ""
}

When creating your entity you must provide a reference, first name & surname - all other fields are optional. 

If you are planning to contact your entity it is good practice to also provide the phone number and/or email address at this stage however they can also be added as part of a process. 

If you are utilising user groups you must provide the relevant userGroupId as part of this request. If you are not utilising user groups you can pass this as an empty string. 

Response body

As part of the response body the API will return an id value, this is referred to as the entityId.

{
  "id": "f8b1971e-f25b-467d-96dd-38351889d85d",
  "firstName": "Test",
  "surname": "Test",
  "dateCreated": "2023-09-12T07:10:13.323",
  "emailAddress": "user@example.com",
  "phoneNumber": "07000000000",
  "entityTags": [],
  "registrationCode": "U94-DMH",
  "status": 0,
  "accountType": 1
}

You should consider storeing this entityId as it is used throughout the Credas API. 

When an entity is initially created via this endpoint it will always have a status of 0 as we have not invited them.

If you are utilising journeys as part of your integration it may be best to create your entity as part of a process as this removes the need for an additional API request.