Create Subscriber Import

POST

api

subscribers

imports

curl --request POST \
  --url https://api.sequenzy.com/api/v1/subscribers/imports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscribers": [
    {}
  ],
  "subscribers[].status": "<string>",
  "subscribers[].timezone": "<string>",
  "subscribers[].customAttributes": {},
  "fileName": "<string>",
  "subscribers[].createdAt": "<string>",
  "duplicateStrategy": "<string>",
  "idempotencyKey": "<string>",
  "listIds": [
    "<string>"
  ],
  "optInMode": "<string>",
  "enrollInSequences": true,
  "defaultPhoneCountry": "<string>",
  "smsConsent": true
}
'

import requests

url = "https://api.sequenzy.com/api/v1/subscribers/imports"

payload = {
    "subscribers": [{}],
    "subscribers[].status": "<string>",
    "subscribers[].timezone": "<string>",
    "subscribers[].customAttributes": {},
    "fileName": "<string>",
    "subscribers[].createdAt": "<string>",
    "duplicateStrategy": "<string>",
    "idempotencyKey": "<string>",
    "listIds": ["<string>"],
    "optInMode": "<string>",
    "enrollInSequences": True,
    "defaultPhoneCountry": "<string>",
    "smsConsent": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subscribers: [{}],
    'subscribers[].status': '<string>',
    'subscribers[].timezone': '<string>',
    'subscribers[].customAttributes': {},
    fileName: '<string>',
    'subscribers[].createdAt': '<string>',
    duplicateStrategy: '<string>',
    idempotencyKey: '<string>',
    listIds: ['<string>'],
    optInMode: '<string>',
    enrollInSequences: true,
    defaultPhoneCountry: '<string>',
    smsConsent: true
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/imports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/subscribers/imports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subscribers' => [
        [
                
        ]
    ],
    'subscribers[].status' => '<string>',
    'subscribers[].timezone' => '<string>',
    'subscribers[].customAttributes' => [
        
    ],
    'fileName' => '<string>',
    'subscribers[].createdAt' => '<string>',
    'duplicateStrategy' => '<string>',
    'idempotencyKey' => '<string>',
    'listIds' => [
        '<string>'
    ],
    'optInMode' => '<string>',
    'enrollInSequences' => true,
    'defaultPhoneCountry' => '<string>',
    'smsConsent' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/subscribers/imports"

	payload := strings.NewReader("{\n  \"subscribers\": [\n    {}\n  ],\n  \"subscribers[].status\": \"<string>\",\n  \"subscribers[].timezone\": \"<string>\",\n  \"subscribers[].customAttributes\": {},\n  \"fileName\": \"<string>\",\n  \"subscribers[].createdAt\": \"<string>\",\n  \"duplicateStrategy\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"listIds\": [\n    \"<string>\"\n  ],\n  \"optInMode\": \"<string>\",\n  \"enrollInSequences\": true,\n  \"defaultPhoneCountry\": \"<string>\",\n  \"smsConsent\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sequenzy.com/api/v1/subscribers/imports")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscribers\": [\n    {}\n  ],\n  \"subscribers[].status\": \"<string>\",\n  \"subscribers[].timezone\": \"<string>\",\n  \"subscribers[].customAttributes\": {},\n  \"fileName\": \"<string>\",\n  \"subscribers[].createdAt\": \"<string>\",\n  \"duplicateStrategy\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"listIds\": [\n    \"<string>\"\n  ],\n  \"optInMode\": \"<string>\",\n  \"enrollInSequences\": true,\n  \"defaultPhoneCountry\": \"<string>\",\n  \"smsConsent\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/subscribers/imports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscribers\": [\n    {}\n  ],\n  \"subscribers[].status\": \"<string>\",\n  \"subscribers[].timezone\": \"<string>\",\n  \"subscribers[].customAttributes\": {},\n  \"fileName\": \"<string>\",\n  \"subscribers[].createdAt\": \"<string>\",\n  \"duplicateStrategy\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"listIds\": [\n    \"<string>\"\n  ],\n  \"optInMode\": \"<string>\",\n  \"enrollInSequences\": true,\n  \"defaultPhoneCountry\": \"<string>\",\n  \"smsConsent\": true\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "import": {
    "id": "import_abc123",
    "batchId": "batch_abc123",
    "status": "running",
    "totalRows": 1,
    "emailCount": 1,
    "duplicateRows": 0
  },
  "message": "Queued 1 subscriber for import."
}

{
  "success": true,
  "deduplicated": true,
  "import": {
    "id": "import_abc123",
    "batchId": "idem-4f2a...",
    "status": "completed",
    "totalRows": 1
  },
  "message": "An import with this idempotency key was already queued."
}

{
  "success": false,
  "retryable": true,
  "importId": "import_abc123",
  "error": "This subscriber import is still being queued by another request. Retry the same idempotency key shortly."
}

Use this endpoint for CRM migrations and first-list onboarding instead of issuing one create request per contact. The request returns 202 immediately; use the returned import ID with Get Subscriber Import.

Permissions

The API key needs subscribers:write. Supplying listIds also requires lists:write; requesting sequence enrollment or double-opt-in delivery requires automations:trigger.

object[]

required

One to 5,000 records. Every record requires an email or a phone (phone-only records import as SMS contacts) and may include externalId, firstName, lastName, phone, status, tags, typed customAttributes, timezone, and createdAt.

string

default:"active"

active, unsubscribed, or bounced, as the source platform reported it. Unsubscribed and bounced records are stored with that status. They never enroll in sequences and never receive a double opt-in confirmation, whatever enrollInSequences and optInMode say. An active record never resubscribes an existing contact who is unsubscribed or bounced, under any duplicateStrategy. With merge or overwrite, an unsubscribed or bounced record applies that status to an existing active contact; an unsubscribe also marks their list memberships unsubscribed and cancels their running sequences. With skip, existing contacts are left unchanged. Map provider values such as AWeber’s Not Confirmed or Mailchimp’s cleaned before sending: send active for contacts who never confirmed, as the dashboard and CLI do, and bounced for cleaned addresses.

string

IANA time zone, such as America/New_York. Invalid or overlong time zones are dropped for that row; they do not reject the whole import.

object

Attribute values may be strings, numbers, booleans, null, or arrays of strings, numbers and booleans. Nested objects and arrays of objects are not supported by this import endpoint.

string

Display name for this import, up to 255 characters, for example crm-export.csv.

string

ISO 8601 date this contact originally signed up on the source platform. Preserves their real history so date-relative segments are correct right after the import. An existing contact’s date only ever moves earlier. If any record carries an unusable value the whole request is rejected with a 400 naming the row, so you never end up with a half-imported list.

string

default:"skip"

skip, merge, or overwrite.

string

Caller-owned key (1-255 characters; blank keys are rejected with a 400) that makes retrying this request safe. The key is scoped to the request content: resending the same request returns the already-queued import with deduplicated: true (as a 200, or as a 202 while the import is still starting up), while different content under the same key queues a new import rather than silently discarding the corrected data. Use it whenever a timeout or retry loop could resend the same import - pipelines should derive it from the sync run (e.g. nightly-sync-2026-08-25). Note this differs from the transactional send Idempotency-Key header, which rejects key reuse with different content.

string[]

List IDs to apply to every imported subscriber. Every ID must belong to the authenticated workspace.

string

default:"default"

default obeys the workspace setting, confirmed imports contacts whose consent has already been verified, and double_opt_in queues confirmation delivery. Keys without automations:trigger must use confirmed for active consented contacts.

boolean

default:"false"

Enroll matching subscribers after import. Requires automations:trigger.

string

Two-letter country code used to normalize national-format phone numbers.

Apply the supplied SMS consent to imported phone numbers. Never infer this from phone presence.

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/imports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "copper-export.csv",
    "duplicateStrategy": "merge",
    "optInMode": "confirmed",
    "listIds": ["list_abc123"],
    "subscribers": [{
      "email": "coach@example.com",
      "externalId": "copper-23",
      "firstName": "Ari",
      "lastName": "Tan",
      "phone": "81234567",
      "tags": ["copper", "consented"],
      "createdAt": "2019-03-14T09:30:00Z",
      "customAttributes": { "source": "Copper", "sessions": 4 }
    }]
  }'

{
  "success": true,
  "import": {
    "id": "import_abc123",
    "batchId": "batch_abc123",
    "status": "running",
    "totalRows": 1,
    "emailCount": 1,
    "duplicateRows": 0
  },
  "message": "Queued 1 subscriber for import."
}

{
  "success": true,
  "deduplicated": true,
  "import": {
    "id": "import_abc123",
    "batchId": "idem-4f2a...",
    "status": "completed",
    "totalRows": 1
  },
  "message": "An import with this idempotency key was already queued."
}

{
  "success": false,
  "retryable": true,
  "importId": "import_abc123",
  "error": "This subscriber import is still being queued by another request. Retry the same idempotency key shortly."
}

A 503 in this form means another request currently owns the short enqueue lease; honor Retry-After and resend the identical request. It does not mean the import failed, and the deterministic import and job IDs keep the retry safe.

A completed import can contain row failures. Always inspect failedCount and failedReasons before treating the migration as successful.

Create Subscriber Import

curl --request POST \
  --url https://api.sequenzy.com/api/v1/subscribers/imports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscribers": [
    {}
  ],
  "subscribers[].status": "<string>",
  "subscribers[].timezone": "<string>",
  "subscribers[].customAttributes": {},
  "fileName": "<string>",
  "subscribers[].createdAt": "<string>",
  "duplicateStrategy": "<string>",
  "idempotencyKey": "<string>",
  "listIds": [
    "<string>"
  ],
  "optInMode": "<string>",
  "enrollInSequences": true,
  "defaultPhoneCountry": "<string>",
  "smsConsent": true
}
'

import requests

url = "https://api.sequenzy.com/api/v1/subscribers/imports"

payload = {
    "subscribers": [{}],
    "subscribers[].status": "<string>",
    "subscribers[].timezone": "<string>",
    "subscribers[].customAttributes": {},
    "fileName": "<string>",
    "subscribers[].createdAt": "<string>",
    "duplicateStrategy": "<string>",
    "idempotencyKey": "<string>",
    "listIds": ["<string>"],
    "optInMode": "<string>",
    "enrollInSequences": True,
    "defaultPhoneCountry": "<string>",
    "smsConsent": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subscribers: [{}],
    'subscribers[].status': '<string>',
    'subscribers[].timezone': '<string>',
    'subscribers[].customAttributes': {},
    fileName: '<string>',
    'subscribers[].createdAt': '<string>',
    duplicateStrategy: '<string>',
    idempotencyKey: '<string>',
    listIds: ['<string>'],
    optInMode: '<string>',
    enrollInSequences: true,
    defaultPhoneCountry: '<string>',
    smsConsent: true
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/imports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/subscribers/imports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subscribers' => [
        [
                
        ]
    ],
    'subscribers[].status' => '<string>',
    'subscribers[].timezone' => '<string>',
    'subscribers[].customAttributes' => [
        
    ],
    'fileName' => '<string>',
    'subscribers[].createdAt' => '<string>',
    'duplicateStrategy' => '<string>',
    'idempotencyKey' => '<string>',
    'listIds' => [
        '<string>'
    ],
    'optInMode' => '<string>',
    'enrollInSequences' => true,
    'defaultPhoneCountry' => '<string>',
    'smsConsent' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/subscribers/imports"

	payload := strings.NewReader("{\n  \"subscribers\": [\n    {}\n  ],\n  \"subscribers[].status\": \"<string>\",\n  \"subscribers[].timezone\": \"<string>\",\n  \"subscribers[].customAttributes\": {},\n  \"fileName\": \"<string>\",\n  \"subscribers[].createdAt\": \"<string>\",\n  \"duplicateStrategy\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"listIds\": [\n    \"<string>\"\n  ],\n  \"optInMode\": \"<string>\",\n  \"enrollInSequences\": true,\n  \"defaultPhoneCountry\": \"<string>\",\n  \"smsConsent\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sequenzy.com/api/v1/subscribers/imports")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscribers\": [\n    {}\n  ],\n  \"subscribers[].status\": \"<string>\",\n  \"subscribers[].timezone\": \"<string>\",\n  \"subscribers[].customAttributes\": {},\n  \"fileName\": \"<string>\",\n  \"subscribers[].createdAt\": \"<string>\",\n  \"duplicateStrategy\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"listIds\": [\n    \"<string>\"\n  ],\n  \"optInMode\": \"<string>\",\n  \"enrollInSequences\": true,\n  \"defaultPhoneCountry\": \"<string>\",\n  \"smsConsent\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/subscribers/imports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscribers\": [\n    {}\n  ],\n  \"subscribers[].status\": \"<string>\",\n  \"subscribers[].timezone\": \"<string>\",\n  \"subscribers[].customAttributes\": {},\n  \"fileName\": \"<string>\",\n  \"subscribers[].createdAt\": \"<string>\",\n  \"duplicateStrategy\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"listIds\": [\n    \"<string>\"\n  ],\n  \"optInMode\": \"<string>\",\n  \"enrollInSequences\": true,\n  \"defaultPhoneCountry\": \"<string>\",\n  \"smsConsent\": true\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "import": {
    "id": "import_abc123",
    "batchId": "batch_abc123",
    "status": "running",
    "totalRows": 1,
    "emailCount": 1,
    "duplicateRows": 0
  },
  "message": "Queued 1 subscriber for import."
}

{
  "success": true,
  "deduplicated": true,
  "import": {
    "id": "import_abc123",
    "batchId": "idem-4f2a...",
    "status": "completed",
    "totalRows": 1
  },
  "message": "An import with this idempotency key was already queued."
}

{
  "success": false,
  "retryable": true,
  "importId": "import_abc123",
  "error": "This subscriber import is still being queued by another request. Retry the same idempotency key shortly."
}

​Permissions

Permissions