Memory API (v1) - Profile endpoints
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.
Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.
Create Profile
List Profiles
Patch Profile Traits
Delete Profile
Bulk Upsert Profiles
Import Profiles
Get a list of imports
Get Import Status
POST/v1/Stores/{storeId}/Profiles
Base url: https://memory.twilio.com (base url)
Create a new profile and set initial traits. The request synchronously resolves identity and either creates a new profile ID or retrieves the associated canonical profile ID based on any provided identifier traits present in the request. The request must contain at least one trait that is promoted to an identifier in its trait group settings. Any additional traits are queued for asynchronous processing.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$application/jsonMultiple trait groups.
{"Contact":{"email":"Alyssa.Mock@example.com","phone":"+13175551234","lastName":"Mock","firstName":"Alyssa","street":"123 Main St","city":"San Francisco","state":"CA","postalCode":"94107","country":"US"}}Max properties: 50Profile resolved and accepted for processing.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createProfile() {11const profile = await client.memory.v112.profiles("mem_store_00000000000000000000000000")13.create({14traits: {},15});1617console.log(profile.id);18}1920createProfile();
Response
1{2"message": "Profile resolved and accepted for processing.",3"id": "mem_profile_00000000000000000000000000"4}
GET/v1/Stores/{storeId}/Profiles
Base url: https://memory.twilio.com (base url)
Return a paginated list of profile IDs ordered by most recently created first. Use the optional paging parameters (pageSize, pageToken, orderBy) to control pagination and sorting. This endpoint is optimized for browsing newly created profiles and lightweight lookups where only the identifiers are needed before requesting full profile details.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The maximum number of items to return per page, maximum of 1000.
50Minimum: 1Maximum: 1000Either 'ASC' or 'DESC' to sort results ascending or descending respectively.
DESCPossible values: ASCDESCA list of profile IDs up to a maximum of 100.
["mem_profile_00000000000000000000000000","mem_profile_00000000000000000000000001","mem_profile_00000000000000000000000002","mem_profile_00000000000000000000000003","mem_profile_00000000000000000000000004","mem_profile_00000000000000000000000005","mem_profile_00000000000000000000000006","mem_profile_00000000000000000000000007","mem_profile_00000000000000000000000008","mem_profile_00000000000000000000000009"]Max items: 1001// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listProfiles() {11const profiles = await client.memory.v112.profiles("mem_store_00000000000000000000000000")13.list({14orderBy: "DESC",15limit: 20,16});1718profiles.forEach((p) => console.log(p));19}2021listProfiles();
Response
1{2"meta": {3"key": "key",4"pageSize": 50,5"nextToken": "nextToken",6"previousToken": "previousToken"7},8"profiles": [9"mem_profile_00000000000000000000000000"10]11}
PATCH/v1/Stores/{storeId}/Profiles/{profileId}
Base url: https://memory.twilio.com (base url)
Merge one or more trait groups into an existing profile. Only the traits provided are added or updated; unspecified traits remain unchanged. Only pre-defined trait groups and traits configured for the memory store can be patched. To remove a trait entirely, set its value to null.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The unique identifier for the profile using Twilio Type ID (TTID) format.
mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$application/jsonMultiple trait groups.
{"Contact":{"email":"Alyssa.Mock@example.com","phone":"+13175551234","lastName":"Mock","firstName":"Alyssa","street":"123 Main St","city":"San Francisco","state":"CA","postalCode":"94107","country":"US"}}Max properties: 50Trait patch accepted.
Trait modifications accepted for processing.Max length: 2551// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function patchProfileTraits() {11const profile = await client.memory.v112.profiles(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000"15)16.patch({17traits: {},18});1920console.log(profile.message);21}2223patchProfileTraits();
Response
1{2"message": "Trait modifications accepted for processing."3}
DELETE/v1/Stores/{storeId}/Profiles/{profileId}
Base url: https://memory.twilio.com (base url)
Asynchronously delete the profile permanently and all associated identifiers and traits. This operation is irreversible. Downstream caches or analytical stores may take time to reflect the deletion. Use cautiously and consider a soft‑delete strategy if regulatory or recovery requirements apply.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The unique identifier for the profile using Twilio Type ID (TTID) format.
mem_profile_00000000000000000000000000Pattern: ^mem_profile_[0-7][0-9a-z]{25}$Profile deletion accepted.
Profile accepted for deletion.Max length: 5121// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteProfile() {11await client.memory.v112.profiles(13"mem_store_00000000000000000000000000",14"mem_profile_00000000000000000000000000"15)16.remove();17}1819deleteProfile();
Response
1{2"message": "Profile accepted for deletion."3}
PUT/v1/Stores/{storeId}/Profiles/Bulk
Base url: https://memory.twilio.com (base url)
Create or update up to 1000 profiles in a single asynchronous batch. Each profile body follows the same structure as single profile creation. If a profile already exists its traits are merged (new keys added, existing keys overwritten). Large batches may take time to process; the 202 response indicates the batch has been accepted. Monitor downstream telemetry or audit logs to confirm completion.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$application/jsonProfiles batch accepted.
Profile batch accepted for processing.Max length: 2551// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateProfilesBulk() {11const bulk = await client.memory.v112.bulk("mem_store_00000000000000000000000000")13.update({14profiles: [15{16traits: {},17},18],19});2021console.log(bulk.message);22}2324updateProfilesBulk();
Response
1{2"message": "Profile batch accepted for processing."3}
POST/v1/Stores/{storeId}/Profiles/Imports
Base url: https://memory.twilio.com (base url)
Initiate a profile import by requesting a pre-signed upload URL and an associated importId. Upload your CSV to the returned URL (single PUT). Query the import status endpoint to track processing progress. This endpoint creates the import task and allocates resources for subsequent ingestion.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$application/jsonThe size of the file in bytes (1 byte to 100 MiB)
1Maximum: 104857600Mappings of CSV header columns to traits' fields
2Max items: 100Import task created.
ID of the import task.
mem_import_00000000000000000000000000Max length: 39Pre-signed URL to upload the CSV via a single PUT request.
https://unified-profiles-csv-upload-stage-us-east-1.s3.amazonaws.com/object.txt?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=vjbyNxybdZaMmLa%2ByT372YEAiv4%3D&Expires=1741978496Max length: 20481// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createProfilesImportV2() {11const import_ = await client.memory.v112.imports("mem_store_00000000000000000000000000")13.create({14filename: "filename",15fileSize: 4404020,16columnMappings: [17{18columnName: "columnName",19traitGroup: "traitGroup",20traitName: "traitName",21},22],23});2425console.log(import_.importId);26}2728createProfilesImportV2();
Response
1{2"importId": "mem_import_00000000000000000000000000",3"url": "https://unified-profiles-csv-upload-stage-us-east-1.s3.amazonaws.com/object.txt?AWSAccessKeyId=AKIA..."4}
GET/v1/Stores/{storeId}/Profiles/Imports
Base url: https://memory.twilio.com (base url)
Retrieve a list of profile import task IDs that have been submitted for this service. Use these IDs to query individual import status details.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$A list of import ids.
1001// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listProfileImportsV2() {11const imports = await client.memory.v112.imports("mem_store_00000000000000000000000000")13.list({ limit: 20 });1415imports.forEach((i) => console.log(i));16}1718listProfileImportsV2();
Response
1{2"imports": [3"mem_import_00000000000000000000000000"4]5}
GET/v1/Stores/{storeId}/Profiles/Imports/{importId}
Base url: https://memory.twilio.com (base url)
Retrieve the current processing status of a previously submitted bulk import task. Query this endpoint using the importId returned from the upload URL request until a terminal state (COMPLETED or FAILED) is reached.
A unique Memory Store ID using Twilio Type ID (TTID) format
mem_store_00000000000000000000000000Pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$The task identifier for the import process.
^mem_import_[0-7][0-9a-z]{25}$Import Status.
Current processing status of the import task
PENDINGPROCESSINGCOMPLETEDFAILEDOriginal filename of the uploaded CSV
profiles_import.csvMax length: 255Timestamp when the import was created
2025-11-14T20:29:21ZTimestamp when the import was last updated
2025-11-14T20:30:15ZSize of the uploaded file in bytes (1 byte to 100 MiB)
204800Minimum: 1Maximum: 104857600Mappings of CSV header columns to traits' fields
2Max items: 1001// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchProfileImportV2() {11const import_ = await client.memory.v112.imports(13"mem_store_00000000000000000000000000",14"mem_import_01111111111111111111111111"15)16.fetch();1718console.log(import_.status);19}2021fetchProfileImportV2();
Response
1{2"columnMappings": [3{4"columnName": "columnName",5"traitGroup": "traitGroup",6"traitName": "traitName"7}8],9"createdAt": "2009-07-06T20:30:00Z",10"fileSize": 204800,11"filename": "filename",12"status": "PENDING",13"summary": {14"errors": 10,15"warnings": 516},17"updatedAt": "2009-07-06T20:30:00Z"18}