Lists Create

Create a new contact list and get the list_id to upload contacts.

POST /api/v1/{account_code}/lists/create
Authorization Bearer {token}  — 56 characters

This endpoint creates a new contact list. The response includes the list_id to be used for uploading contacts via the upload-contacts endpoint.

List creation limit The endpoint automatically checks the maximum number of lists allowed by your plan. If the limit is reached, creation fails with a 403 error.
Automatic category management If you specify a category, the endpoint checks whether it already exists for your account. If it does not, it creates it automatically. The field category_info.category_created in the response tells you whether it was just created (true) or already existed (false).

Parameters (JSON)

Parameter Required Type Description
name YES string List name (e.g. "February 2026 Clients")
category YES string Category (e.g. "Clients", "Newsletter"). Created automatically if it does not exist.
default_domain YES string Domain used to send confirmation emails (double opt-in) to contacts who sign up through a form linked to the list.
reminder NO string Reminder text displayed to subscribers

Optional List Info

Additional data stored as list metadata.

Parameter Type Description
representativestringRepresentative name
emailstringContact email
companystringCompany name
vatstringVAT number
citystringCity
addressstringFull address
zipstringPostal code
provincestringProvince / State
countrystringCountry
phone_prefixstringPhone prefix (e.g. +39)
phonestringPhone number
websitestringWebsite URL

Example Request

JSON 
{
  "name": "February 2026 Clients",
  "category": "Clients",
  "reminder": "You are receiving this because you subscribed to my list",
  "default_domain": "example.com",
  "representative": "John Smith",
  "email": "info@example.com",
  "company": "Acme Corporation",
  "vat": "IT12345678901",
  "city": "Milan",
  "address": "Via Roma 123",
  "zip": "20100",
  "province": "MI",
  "country": "Italy",
  "phone_prefix": "+39",
  "phone": "0212345678",
  "website": "https://www.example.com"
}

Success Response

201 Created
JSON 
{
  "success": true,
  "message": "List created successfully.",
  "data": {
    "list_id": 123,
    "name": "February 2026 Clients",
    "category": "Clients",
    "created_at": "2026-02-11 15:30:45",
    "categoria_info": {
      "category_id": 8,
      "category_created": false
    }
  }
}

Response Fields

Field Type Description
successbooleanOperation result
messagestringDescriptive message
data.list_idintegerCreated list ID — use this to upload contacts
data.namestringList name
data.categorystringList category
data.created_atstringCreation timestamp (format: Y-m-d H:i:s)
data.categoria_infoobjectPresent only when a category was specified
data.categoria_info.category_idintegerID of the verified/created category
data.categoria_info.category_createdbooleantrue if just created, false if it already existed

Common Errors

400 Bad Request
JSON 
{
  "success": false,
  "message": "Necessary data is missing."
}
403 Forbidden — Limit reached
JSON 
{
  "success": false,
  "message": "Failed to create list. You may have reached your list creation limit."
}
403 Forbidden — Invalid token
JSON 
{
  "success": false,
  "message": "NO Token Found."
}

Full Flow: Create List + Upload Contacts

1
Create the list
JSON Request 
POST /api/v1/{account_code}/lists/create
Content-Type: application/json

{
  "name": "February 2026 Clients",
  "category": "Clients"
}

// → Response: { "data": { "list_id": 123 } }
2
Upload contacts using the list_id
JSON Request 
POST /api/v1/{account_code}/lists/upload-contacts
Content-Type: application/json

{
  "list_id": 123,
  "add_prefix": 1,
  "default_prefix": "+39",
  "column_headers": ["FIRST_NAME", "LAST_NAME", "EMAIL", "PHONE"],
  "column_types": ["text", "text", "email", "phone"],
  "data_build": [
    ["Mario", "Rossi", "mario.rossi@email.com", "3331234567"],
    ["Laura", "Bianchi", "laura.bianchi@email.com", "3407654321"]
  ]
}

// → Response: { "success": true, "contacts_processed": 2 }