Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Entity Resource

The Entity resource represents a user or other identity that needs verification. A Service contains Entities and an Entity contains Factors.

Entity Properties

entity-properties page anchor
(warning)

Warning

Do not use Personally Identifiable Information for identity. Use an immutable user identifier like a system UUID, GUID, or SID.
Verify Push uses identity as a unique identifier of a user. You should not use directly identifying information (aka personally identifiable information or PII) like a person's name, home address, email or phone number, etc., as identity because the systems that will process this attribute assume it is not directly identifying information.

Property nameTypeRequiredDescriptionChild properties
sidSID<YE>

Optional

Not PII

A 34 character string that uniquely identifies this Entity.

Pattern: ^YE[0-9a-fA-F]{32}$Min length: 34Max length: 34
identitystring

Optional

PII MTL: 30 days

The unique external identifier for the Entity of the Service. This identifier should be immutable, not PII, length between 8 and 64 characters, and generated by your external system, such as your user's UUID, GUID, or SID. It can only contain dash (-) separated alphanumeric characters.

accountSidSID<AC>

Optional

Not PII

The unique SID identifier of the Account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
serviceSidSID<VA>

Optional

Not PII

The unique SID identifier of the Service.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34
dateCreatedstring<date-time>

Optional

Not PII

The date that this Entity was created, given in ISO 8601(link takes you to an external page) format.

dateUpdatedstring<date-time>

Optional

Not PII

The date that this Entity was updated, given in ISO 8601(link takes you to an external page) format.

urlstring<uri>

Optional

Not PII

The URL of this resource.

linksobject<uri-map>

Optional

Not PII

Contains a dictionary of URL links to nested resources of this Entity.

Create an Entity resource

create-an-entity-resource page anchor

POST https://verify.twilio.com/v2/Services/{ServiceSid}/Entities

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<VA>
required
Not PII

The unique SID identifier of the Service.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
identitystring
required
PII MTL: 30 days

The unique external identifier for the Entity of the Service. This identifier should be immutable, not PII, length between 8 and 64 characters, and generated by your external system, such as your user's UUID, GUID, or SID. It can only contain dash (-) separated alphanumeric characters.

Create an EntityLink to code sample: Create an Entity
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createEntity() {

11
  const entity = await client.verify.v2

12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .entities.create({ identity: "Identity" });

14


15
  console.log(entity.sid);

16
}

17


18
createEntity();

Response

1
{

2
  "sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "identity": "Identity",

4
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

6
  "date_created": "2015-07-30T20:00:00Z",

7
  "date_updated": "2015-07-30T20:00:00Z",

8
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f",

9
  "links": {

10
    "factors": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors",

11
    "new_factors": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors",

12
    "challenges": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges"

13
  }

14
}

Fetch an Entity resource

fetch-an-entity-resource page anchor

GET https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<VA>
required
Not PII

The unique SID identifier of the Service.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34
identitystring
required
PII MTL: 30 days

The unique external identifier for the Entity of the Service. This identifier should be immutable, not PII, length between 8 and 64 characters, and generated by your external system, such as your user's UUID, GUID, or SID. It can only contain dash (-) separated alphanumeric characters.

Fetch an EntityLink to code sample: Fetch an Entity
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchEntity() {

11
  const entity = await client.verify.v2

12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .entities("Identity")

14
    .fetch();

15


16
  console.log(entity.sid);

17
}

18


19
fetchEntity();

Response

1
{

2
  "sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "identity": "Identity",

4
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

6
  "date_created": "2015-07-30T20:00:00Z",

7
  "date_updated": "2015-07-30T20:00:00Z",

8
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f",

9
  "links": {

10
    "factors": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors",

11
    "new_factors": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors",

12
    "challenges": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges"

13
  }

14
}

Read multiple Entity resources

read-multiple-entity-resources page anchor

GET https://verify.twilio.com/v2/Services/{ServiceSid}/Entities

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<VA>
required
Not PII

The unique SID identifier of the Service.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
pageSizeinteger<int64>

Optional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

The page index. This value is simply for client state.

Minimum: 0
pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

List multiple EntitysLink to code sample: List multiple Entitys
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listEntity() {

11
  const entities = await client.verify.v2

12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .entities.list({ limit: 20 });

14


15
  entities.forEach((e) => console.log(e.sid));

16
}

17


18
listEntity();

Response

1
{

2
  "entities": [],

3
  "meta": {

4
    "page": 0,

5
    "page_size": 50,

6
    "first_page_url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities?PageSize=50&Page=0",

7
    "previous_page_url": null,

8
    "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities?PageSize=50&Page=0",

9
    "next_page_url": null,

10
    "key": "entities"

11
  }

12
}

Delete an Entity resource

delete-an-entity-resource page anchor

DELETE https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}

Path parameters

path-parameters-3 page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<VA>
required
Not PII

The unique SID identifier of the Service.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34
identitystring
required
Not PII

The unique external identifier for the Entity of the Service. This identifier should be immutable, not PII, length between 8 and 64 characters, and generated by your external system, such as your user's UUID, GUID, or SID. It can only contain dash (-) separated alphanumeric characters.

Delete an EntityLink to code sample: Delete an Entity
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function deleteEntity() {

11
  await client.verify.v2

12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .entities("Identity")

14
    .remove();

15
}

16


17
deleteEntity();