Skip to main content
Read, create, update, and delete lists and processes. The process flag distinguishes a regular list (false) from a process (true).

​
List all lists & processes

curl https://api.relate.so/v1/lists \
  -H "Authorization: Bearer {api_key}"

{
    "data": [
        {
            "id": "QbkUlo",
            "name": "test list",
            "process": false,
            "entry_type": "Organization",
            "fields": [
                { "name": "test field", "data_type": "text" }
            ],
            "created_at": "2025-04-29T22:47:39.635Z",
            "updated_at": "2025-04-29T22:47:39.635Z",
            "archived_at": null
        },
        {
            "id": "Jm9UpJ",
            "name": "test process",
            "identifier": "TEST PROCE",
            "process": true,
            "duplicates_allowed": true,
            "entry_type": "Organization",
            "entry_label": "Organization",
            "status_label": "Status",
            "statuses": [
                { "name": "Started", "type": "active" },
                { "name": "In Progress", "type": "active" },
                { "name": "Completed", "type": "won" },
                { "name": "Canceled", "type": "lost" }
            ],
            "fields": [
                { "name": "test field", "data_type": "text" }
            ],
            "created_at": "2025-04-29T22:47:28.540Z",
            "updated_at": "2025-04-29T22:47:28.540Z",
            "archived_at": null
        }
    ],
    "pagination": { "end_cursor": 2, "has_next_page": false, "total_count": 2 }
}

​
Retrieve a list or process

curl https://api.relate.so/v1/lists/:list_id \
  -H "Authorization: Bearer {api_key}"
Regular list response: 
{
    "id": "QbkUlo",
    "name": "test list",
    "process": false,
    "entry_type": "Organization",
    "fields": [ { "name": "test field", "data_type": "text" } ],
    "created_at": "2025-04-29T22:47:39.635Z",
    "updated_at": "2025-04-29T22:47:39.635Z",
    "archived_at": null
}
Process response: 
{
    "id": "Jm9UpJ",
    "name": "test process",
    "identifier": "TEST PROCE",
    "process": true,
    "duplicates_allowed": true,
    "entry_type": "Organization",
    "entry_label": "Organization",
    "status_label": "Status",
    "statuses": [
        { "name": "Started", "type": "active" },
        { "name": "In Progress", "type": "active" },
        { "name": "Completed", "type": "won" },
        { "name": "Canceled", "type": "lost" }
    ],
    "fields": [ { "name": "test field", "data_type": "text" } ],
    "created_at": "2025-04-29T22:47:28.540Z",
    "updated_at": "2025-04-29T22:47:28.540Z",
    "archived_at": null
}

​
Create a list

curl -X POST https://api.relate.so/v1/lists \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "...",
    "process": false,
    "entry_type": "Contact",
    "fields": [
      { "name": "...", "data_type": "select", "accepts_multiple_values": false, "options": ["option1", "option2", "option3"] },
      { "name": "...", "data_type": "textarea" }
    ]
  }'
  • name (required): Name of the list
  • process (required): Whether this is a process (true) or a regular list (false)
  • entry_type (required): Type of entries. Must be "Contact" or "Organization"
  • fields (optional): Array of custom field definitions for entries
    • name (required): Name of the field
    • data_type (required): One of text, textarea, url, number, date, datetime, select, user, contact
    • accepts_multiple_values (required for select/user/contact): Whether multiple values are allowed
    • options (required for select): Array of selectable options

​
Create a process

curl -X POST https://api.relate.so/v1/lists \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "...",
    "process": true,
    "entry_type": "Contact",
    "identifier": "...",
    "duplicates_allowed": false,
    "entry_label": "...",
    "status_label": "...",
    "statuses": [
      { "name": "...", "type": "active" },
      { "name": "...", "type": "active" },
      { "name": "...", "type": "done" }
    ],
    "fields": [
      { "name": "...", "data_type": "select", "accepts_multiple_values": false, "options": ["option1", "option2", "option3"] },
      { "name": "...", "data_type": "date" }
    ]
  }'
  • name (required): Name of the process
  • process (required): Must be true to indicate this is a process
  • entry_type (required): Type of entries. Must be "Contact" or "Organization"
  • identifier (required): Field used to uniquely identify entries (e.g. "DEAL")
  • duplicates_allowed (required): Whether multiple entries with the same identifier are allowed
  • statuses (optional): Array of status stages. Each must include:
    • name (required): Label for the stage (e.g. "Onboarding")
    • type (required): One of active, won, lost
  • entry_label (optional): Custom label for an individual entry (e.g. "Lead", "Candidate")
  • status_label (optional): Custom label for the status field (e.g. "Stage", "Status")
  • fields (optional): Array of additional custom fields (same format as Create a list)

​
Update a list or process

curl -X PATCH https://api.relate.so/v1/lists/:list_id \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "...",
    "identifier": "...",
    "duplicates_allowed": false,
    "entry_label": "...",
    "status_label": "...",
    "statuses": [
      { "name": "...", "type": "active" },
      { "name": "...", "type": "done" }
    ],
    "fields": [
      { "name": "...", "data_type": "date" }
    ]
  }'
  • entry_type and process cannot be updated.

​
Delete a list or process

curl -X DELETE https://api.relate.so/v1/lists/:list_id \
  -H "Authorization: Bearer {api_key}"