Skip to content Skip to navigation Skip to topbar

Memory API (v1) - Identity Resolution Settings endpoints

(information)

Legal information

Conversation Memory, including the APIs, may use artificial intelligence or machine learning technologies and is subject to the terms of the Predictive and Generative AI/ML Features Addendum. For more details on AI usage and data, see the AI Nutrition Facts.

Conversation Memory is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.

Conversation Memory is not intended for use with sensitive information about individuals. Twilio does not control what information comes from conversation channels and relies on you to ensure the data in customer profiles aligns with our acceptable use policy. Twilio does have limited guardrails in the form of a prompt exclusion that is designed to provide a minimal screening against inclusion of GDPR special category data. As a reminder our profile technology uses generative artificial intelligence. Because generative artificial intelligence can make mistakes, review all outputs to ensure that the profile is correct.

Overview

Tag description

Endpoints

/v1/ControlPlane/Stores/{storeId}/IdentityResolutionSettings

Retrieve Identity Resolution Settings

/v1/ControlPlane/Stores/{storeId}/IdentityResolutionSettings

Update Identity Resolution Settings

Retrieve Identity Resolution Settings

GET/v1/ControlPlane/Stores/{storeId}/IdentityResolutionSettings

Base url: https://memory.twilio.com (base url)

These settings determine how Customer Memory will use identifiers for searching, merging, and resolving profiles.

Some settings can only take on their default values and are not yet available to change, but coming soon.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

storeIdstring

required

A unique Memory Store ID using Twilio Type ID (TTID) format

Example: mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$

Responses

200400404429500503

Identity resolution settings retrieved successfully

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

identifierConfigsarray[object]

Optional

List of identifier types and their resolution settings.

Min items: 1Max items: 15

Show identifierConfigs properties

Property nameTypeRequiredPIIDescriptionChild properties

idTypestring

Optional

Name of the identifier type. Usual values are email, phone, external_id etc.

Example: emailMin length: 2Max length: 30

matchingAlgoenum<string>

Optional

The algorithm to use for matching identifier values.

exact, exact string match.
fuzzy, low precision match allowing for some variations.

Default: exactPossible values:

exactfuzzy

matchingThresholdinteger

Optional

The fuzzy matching threshold percentage.

Default: 75Minimum: 50Maximum: 99

limitinteger

Optional

Maximum number of historical values to retain.

Default: 100Minimum: 1Maximum: 100

limitPolicyenum<string>

Optional

Removal policy to apply when the number of values exceeds the limit and is based on the timestamp of the request when the identifier was added.

fifo: First In First Out, removes the oldest values first.
lifo: Last In First Out, removes the most recent values first.

Default: fifoExample: fifoPossible values:

fifolifo

enforceUniqueboolean

Optional

When enabled, more than one profile may not share the same identifier value. Adding a shared identifier to a second profile may trigger a merge. Disabling creates a compound identifier where merges are only triggered if two or more identifiers satisfy a matching rule.

Default: trueExample: true

normalizationenum<string>

Optional

Normalization to apply to the identifier value before storing and matching.

phone: Normalize phone numbers to E.164 format.
email: Normalize email addresses by coverting to lowercase and removing spaces.
trim: Removes spaces from both ends of the string.
none: No normalization.

Important Note for Phone Number Normalization: When using the phone normalization option, please adhere to the following guidelines to ensure proper formatting:

All US numbers must be at least valid 10 digit phone numbers with area code. They may also include or omit the "+1" prefix.
Non-US numbers must include a 1-3 digit country code (a "+" prefix is optional). Non-US national formats are not supported and will be interpreted as US numbers.

Default: trimExample: emailPossible values:

phoneemailtrimnone

matchingRulesarray[string]

Optional

Priority list of identifiers to locate profiles to apply new data to, or for determining if two existing profiles should merge. Rules are evaluated in order.

If no rule matches against existing profiles, a new profile will be created.
If a rule matches to a single existing profile, the profile will be updated.
If a rule matches to multiple existing profiles, those existing profiles will be merged.

Example: ["email","whatsapp","phone"]Min items: 1Max items: 15

versioninteger

Optional

The current version number of the Identity Resolution Settings. Incremented on each successful update.

Example: 3Minimum: 1

Bad Request

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Not Found

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

This error indicates that you have sent too many requests to the API. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Internal Server Error

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Service Unavailable

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Retrieve Identity Resolution Settings

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchIdentityResolutionSettings() {
11  const identityResolutionSetting = await client.memory.v1
12    .identityResolutionSettings("mem_store_00000000000000000000000000")
13    .fetch();
14
15  console.log(identityResolutionSetting.identifierConfigs);
16}
17
18fetchIdentityResolutionSettings();

Response

1{
2  "identifierConfigs": [
3    {
4      "idType": "idType",
5      "matchingAlgo": "exact",
6      "matchingThreshold": 75,
7      "limit": 100,
8      "limitPolicy": "fifo",
9      "enforceUnique": true,
10      "normalization": "email"
11    }
12  ],
13  "matchingRules": [
14    "matchingRules"
15  ],
16  "version": 3
17}

Update Identity Resolution Settings

PUT/v1/ControlPlane/Stores/{storeId}/IdentityResolutionSettings

Base url: https://memory.twilio.com (base url)

Update the identity resolution settings for this memory store, which determine how Customer Memory will use identifiers for searching, merging, and resolving profiles.

Request

Security: Basic Auth

Headers

Property nameTypeRequiredPIIDescription

if-Matchstring

Optional

Allows for optimistic concurrency control by making the request conditional. Server will only act if the resource's current Entity Tag (ETag) matches the one provided, preventing accidental overwrites.

Example: "eyJpZCI6ImFuX2lkIiwidiI6MX0"Max length: 100

Path parameters

Property nameTypeRequiredPIIDescription

storeIdstring

required

A unique Memory Store ID using Twilio Type ID (TTID) format

Example: mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

identifierConfigsarray[object]

Optional

List of identifier types and their resolution settings.

Min items: 1Max items: 15

Show identifierConfigs properties

Property nameTypeRequiredPIIDescriptionChild properties

idTypestring

required

Name of the identifier type. Usual values are email, phone, external_id etc.

Example: emailMin length: 2Max length: 30

matchingAlgoenum<string>

Optional

The algorithm to use for matching identifier values.

exact, exact string match.
fuzzy, low precision match allowing for some variations.

Default: exactPossible values:

exactfuzzy

matchingThresholdinteger

Optional

The fuzzy matching threshold percentage.

Default: 75Minimum: 50Maximum: 99

limitinteger

Optional

Maximum number of historical values to retain.

Default: 100Minimum: 1Maximum: 100

limitPolicyenum<string>

Optional

Removal policy to apply when the number of values exceeds the limit and is based on the timestamp of the request when the identifier was added.

fifo: First In First Out, removes the oldest values first.
lifo: Last In First Out, removes the most recent values first.

Default: fifoExample: fifoPossible values:

fifolifo

enforceUniqueboolean

Optional

When enabled, more than one profile may not share the same identifier value. Adding a shared identifier to a second profile may trigger a merge. Disabling creates a compound identifier where merges are only triggered if two or more identifiers satisfy a matching rule.

Default: trueExample: true

normalizationenum<string>

Optional

Normalization to apply to the identifier value before storing and matching.

phone: Normalize phone numbers to E.164 format.
email: Normalize email addresses by coverting to lowercase and removing spaces.
trim: Removes spaces from both ends of the string.
none: No normalization.

Important Note for Phone Number Normalization: When using the phone normalization option, please adhere to the following guidelines to ensure proper formatting:

All US numbers must be at least valid 10 digit phone numbers with area code. They may also include or omit the "+1" prefix.
Non-US numbers must include a 1-3 digit country code (a "+" prefix is optional). Non-US national formats are not supported and will be interpreted as US numbers.

Default: trimExample: emailPossible values:

phoneemailtrimnone

matchingRulesarray[string]

Optional

Priority list of identifiers to locate profiles to apply new data to, or for determining if two existing profiles should merge. Rules are evaluated in order.

If no rule matches against existing profiles, a new profile will be created.
If a rule matches to a single existing profile, the profile will be updated.
If a rule matches to multiple existing profiles, those existing profiles will be merged.

Example: ["email","whatsapp","phone"]Min items: 1Max items: 15

Responses

202400404429500503

Identity Resolution Settings accepted for processing.

Schema

Property nameTypeRequiredPIIDescriptionChild properties

messagestring

Optional

Example: Identity Resolution Settings accepted for processing.Max length: 512

statusUrlstring

Optional

URI to check operation status.

Max length: 512

Bad Request

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Not Found

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

This error indicates that you have sent too many requests to the API. You should retry according to the Retry-After response header.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Internal Server Error

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Service Unavailable

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

The Twilio error code.

Minimum: 100Maximum: 99999

messagestring

Optional

A human readable message describing the error.

Max length: 1024

moreInfostring

Optional

A URL to a Twilio error directory page with more information about the error code.

statusinteger<int32>

Optional

The HTTP status code for the error.

Minimum: 100Maximum: 599

Update Identity Resolution Settings

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateIdentityResolutionSettings() {
11  const identityResolutionSetting = await client.memory.v1
12    .identityResolutionSettings("mem_store_00000000000000000000000000")
13    .update({
14      identifierConfigs: [
15        {
16          idType: "idType",
17          matchingAlgo: "exact",
18          matchingThreshold: 75,
19          limit: 100,
20          limitPolicy: "fifo",
21          enforceUnique: true,
22          normalization: "email",
23        },
24      ],
25    });
26
27  console.log(identityResolutionSetting.message);
28}
29
30updateIdentityResolutionSettings();

Response

1{
2  "message": "message",
3  "statusUrl": "statusUrl"
4}