APIs to upload CSV files containing lists of people. These endpoints provide a convenient way to add and update people without having to make an `identify` call for each individual person.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/customer-io:customer-io-imports-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 1.0.0
title: Customer.io Journeys API Reference Imports API
description: Customer.io provides REST APIs to send real-time customer data, retrieve data from your account, and trigger messages.
servers:
- url: https://track.customer.io
description: The base URL for the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://track-eu.customer.io
description: The base URL for the Track API (EU region). Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Imports
description: APIs to upload CSV files containing lists of people. These endpoints provide a convenient way to add and update people without having to make an `identify` call for each individual person.
paths:
/v1/imports:
servers:
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
post:
operationId: import
summary: Import items in bulk
security:
- Bearer-Auth: []
description: 'This endpoint lets you upload a CSV file containing people, events, objects, or relationships. It provides a handy way of adding and updating them in bulk. Uploading people, objects, or relationships is like performing an `identify` call for each row in your CSV; uploading events is like performing a `track` call.
You''ll need to provide us the public URL of your CSV as a part of this operation. We recommend that you host your CSVs from short-lived URLs. Ideally, your URLs will expire 2 hours after you initiate an import so that your customers'' information doesn''t remain publicly available after you''ve uploaded it to us.
Check out the CSV requirements based on what you''re importing: people, events, and objects or relationships.
This endpoint performs some basic validation on the request and then queues the import for processing. The import happens in multiple stages after your request, and may even fail. You''ll need to lookup the status of the import to check on its progress.
Records in your CSV might result in errors or warnings during the import. We make the errors and warnings available in CSV files that you can download via our export endpoints. Lookup your import to get download URLs for error and warning reports.'
tags:
- Imports
requestBody:
content:
application/json:
schema:
type: object
required:
- import
properties:
import:
$ref: '#/components/schemas/import_request'
responses:
'200':
description: Returns an import payload.
content:
application/json:
schema:
type: object
required:
- import
properties:
import:
$ref: '#/components/schemas/import_object'
'429':
$ref: '#/components/responses/429'
/v1/imports/{import_id}:
servers:
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
get:
operationId: getImport
parameters:
- name: import_id
in: path
required: true
description: The `id` of the import you want to lookup. This value is [returned from an import](/integrations/api/app/tag/imports/import/) that was accepted and queued for processing.
schema:
type: integer
summary: Retrieve a bulk import
security:
- Bearer-Auth: []
description: This endpoint returns information about an "import"—a CSV file containing a group of people or events you uploaded to using `v1/imports` endpoint. You can use this endpoint to check to status of imports, or find out how many rows you successfully imported from a CSV file.
tags:
- Imports
responses:
'200':
description: Returns an import payload.
content:
application/json:
schema:
type: object
required:
- import
properties:
import:
allOf:
- $ref: '#/components/schemas/import_object'
- type: object
properties:
error_export_id:
type: integer
example: 2
description: ID of the export containing errors for the import, which can retrieved via [the *Get an export* endpoint](/integrations/api/app/tag/exports/getExport/). Only present when there are errors.
error_download_url:
type: string
example: https://api.customer.io/v1/exports/2/download
description: URL to download errors for the import via [the *Download an export* endpoint](/integrations/api/app/tag/exports/downloadExport/). Only present when there are errors.
warning_export_id:
type: integer
example: 1
description: ID of the export containing warnings for the import, which can retrieved via [the *Get an export* endpoint](/integrations/api/app/tag/exports/getExport/). Only present when there are warnings.
warning_download_url:
type: string
example: https://api.customer.io/v1/exports/1/download
description: URL to download warnings for the import via [the *Download an export* endpoint](/integrations/api/app/tag/exports/downloadExport/). Only present when there are warnings.
'429':
$ref: '#/components/responses/429'
components:
schemas:
appApiError:
x-scalar-ignore: true
type: object
description: An array/list of failures where each entry is a separate failure reason.
required:
- errors
properties:
errors:
type: array
description: One entry for each reason the request failed.
items:
type: object
required:
- detail
- status
properties:
detail:
type: string
description: What went wrong, in plain text. Most messages end with a support reference you can use if you need to contact support.
example: bad request (reference a1b2c3)
status:
type: string
description: The HTTP status code as a string.
example: '400'
code:
type: string
description: A stable identifier for the failure, on the errors that carry one. Use this rather than the text in `detail` if you need to identify the error programmatically.
example: invalid_credentials
source:
type: object
description: The part of the request that the error refers to.
properties:
pointer:
type: string
description: A JSON pointer to the part of the request body that the error refers to.
example: /data/attributes/email
meta:
type: object
additionalProperties: true
description: Extra context (if available).
import_name:
x-scalar-ignore: true
type: string
description: A friendly name for your import. This helps you identify your import.
import_description:
x-scalar-ignore: true
type: string
description: A helpful description that can help you find and recognize your import operation.
rows_to_import:
x-scalar-ignore: true
type: integer
description: The total number of importable rows we found in the CSV.
created:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was created.
example: 1552341937
readOnly: true
import_object:
x-scalar-ignore: true
description: Represents an import operation.
type: object
properties:
id:
type: integer
description: This is the `import_id` you'll use if you want to [lookup your import operation](/integrations/api/app/tag/imports/getImport/).
created_at:
$ref: '#/components/schemas/created'
updated_at:
$ref: '#/components/schemas/updated'
name:
$ref: '#/components/schemas/import_name'
description:
$ref: '#/components/schemas/import_description'
rows_to_import:
$ref: '#/components/schemas/rows_to_import'
rows_imported:
$ref: '#/components/schemas/rows_imported'
state:
$ref: '#/components/schemas/import_state'
type:
$ref: '#/components/schemas/import_type'
identifier:
type: string
description: The type of identifier you used to identify people in your CSV. Not applicable for object imports.
enum:
- id
- email
data_to_process:
$ref: '#/components/schemas/data_to_process'
people_to_process:
type: string
description: 'Returned for people and event imports, even if you imported using the field `data_to_process`. This field will be deprecated soon.
'
enum:
- all
- only_new
- only_existing
object_type_id:
type: string
description: The object type an object belongs to—like "Companies" or "Accounts". Only applies to object imports.
example: '1'
error:
description: If your import fails, this helps you understand why.
type: string
example:
id: 30
name: account-object-import
description: importing accounts
created_at: 1706081641
updated_at: 1706081645
rows_to_import: 3
rows_imported: 3
state: imported
type: object
data_to_process: all
people_to_process: all
object_type_id: 1
error: possible error - The specified Object Type does not exist.
data_to_process:
x-scalar-ignore: true
type: string
description: Controls whether your import adds and updates all rows, adds only new rows, or updates only existing rows. Defaults to `all`. Event imports support only `all` and `only_existing`. Formerly called `people_to_process`.
enum:
- all
- only_new
- only_existing
import_type:
x-scalar-ignore: true
type: string
description: The type of import.
enum:
- people
- event
- object
- relationship
import_request:
x-scalar-ignore: true
oneOf:
- title: people
type: object
description: Contains your import parameters.
required:
- data_file_url
- name
- type
- identifier
properties:
name:
$ref: '#/components/schemas/import_name'
data_file_url:
type: string
description: The URL or path to the CSV file you want to import.
type:
type: string
description: The type of import.
enum:
- people
identifier:
$ref: '#/components/schemas/import_identifier'
data_to_process:
$ref: '#/components/schemas/data_to_process'
description:
$ref: '#/components/schemas/import_description'
- title: event
type: object
description: Contains your import parameters.
required:
- data_file_url
- name
- type
- identifier
properties:
name:
$ref: '#/components/schemas/import_name'
data_file_url:
type: string
description: The URL or path to the CSV file you want to import.
type:
type: string
description: The type of import.
enum:
- event
identifier:
$ref: '#/components/schemas/import_identifier'
data_to_process:
$ref: '#/components/schemas/data_to_process'
description:
$ref: '#/components/schemas/import_description'
- title: relationship
type: object
description: Contains your import parameters.
required:
- data_file_url
- name
- type
- identifier
properties:
name:
$ref: '#/components/schemas/import_name'
data_file_url:
type: string
description: The URL or path to the CSV file you want to import.
type:
type: string
description: The type of import.
enum:
- relationship
identifier:
type: string
description: The type of identifier used to identify the person in each relationship—`id`, `email`, or `cio_id`.
enum:
- id
- email
- cio_id
data_to_process:
$ref: '#/components/schemas/data_to_process'
description:
$ref: '#/components/schemas/import_description'
- title: object
type: object
description: Contains your import parameters.
required:
- data_file_url
- name
- type
- object_type_id
properties:
name:
$ref: '#/components/schemas/import_name'
data_file_url:
type: string
description: The URL or path to the CSV file you want to import.
object_type_id:
$ref: '#/components/schemas/object_type_id'
type:
type: string
description: The type of import.
enum:
- object
data_to_process:
$ref: '#/components/schemas/data_to_process'
description:
$ref: '#/components/schemas/import_description'
object_type_id:
x-scalar-ignore: true
type: string
description: The object type an object belongs to—like "Companies" or "Accounts". Object type IDs are string-formatted integers that begin at `1` and increment for each new type.
example: '1'
updated:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was last updated.
example: 1552341937
readOnly: true
import_identifier:
x-scalar-ignore: true
type: string
description: The type of identifier you want to use to identify people in your sheet—`id` or `email`. At least one column in the CSV must contain an identifier.
enum:
- id
- email
rows_imported:
x-scalar-ignore: true
type: integer
description: The number of rows we imported from the CSV.
import_state:
x-scalar-ignore: true
type: string
description: The state of the import—whether your import is being processed, fully completed (`imported`), or if it failed.
enum:
- preprocessing
- preprocessed
- validating
- validated
- importing
- imported
- failed
- canceled
responses:
'429':
description: Your request is over the 10-per-second limit. `Retry-After` tells you how many seconds you must wait before you send the next request.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/appApiError'
example:
errors:
- detail: rate limited to 10 requests per 1s (reference a1b2c3)
status: '429'
headers:
Retry-After:
description: How many seconds you must wait before you send another request. This header is present when you are rate limited by a per-second limit. If you hit a daily quota, this header is not set.
schema:
type: integer
minimum: 1
example: 1
securitySchemes:
Tracking-API-Key:
type: http
scheme: basic
description: 'The Track API uses a basic authentication scheme. Your credentials are your **Site ID** and your **API key**, **Base-64 encoded** in the format `site_id:api_key`.
You can find your Site ID and API key on the [Track API Keys page](https://fly.customer.io/settings/api_credentials).
'
Bearer-Auth:
type: http
scheme: bearer
description: 'The App API uses a bearer authentication scheme.
You can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).
'
ServiceAccount-Auth:
x-scalar-ignore: true
type: http
scheme: bearer
bearerFormat: sa_live_
description: 'Transactional send endpoints (`/v1/send/email`, `/v1/send/push`, `/v1/send/sms`, `/v1/send/whatsapp`, `/v1/send/in_app`, `/v1/send/inbox_message`) also accept a service-account bearer token, prefixed with `sa_live_`. Service-account tokens work across workspaces, so you must pass the target workspace as the `X-Workspace-Id` header on each request.
Service-account tokens are intended for testing and one-off sends—for example, using the Customer.io CLI with an AI agent like Claude to verify that a transactional message renders correctly before wiring it into your production backend. **For the production integration that triggers the message from your application, use an App API Key instead**: it''s workspace-scoped, easier to rotate, and has a smaller blast radius.
Service-account tokens are server-side credentials. Treat them like any API key—keep them in environment variables or a secret manager, and never embed them in client-side code, mobile apps, or other untrusted contexts.
'
bearerAuth:
type: http
scheme: bearer
description: API key passed as a Bearer token.
x-tagGroups:
- name: Track API v2
tags:
- track_v2
- Object Schemas
- Person Schemas
- Deliveries
- name: Track API
tags:
- trackOverview
- trackJsOrBackend
- trackLimit
- trackRegion
- Track Customers
- Track Events
- Forms
- Track Segments
- Track v1 Overview
- name: App API
tags:
- appOverview
- appLimit
- appAuth
- Activities
- Automations
- Broadcasts
- Collections
- Customers
- Data Index
- ESP Suppression
- Exports
- Imports
- Info
- Live Notifications
- Messages
- Newsletters
- Opt-outs
- Reporting Webhooks
- Segments
- Sender Identities
- Snippets
- Subscription Center
- Transactional
- Workspaces
- Send Messages
- Objects
- Newsletter Variants
- Newsletter Metrics
- Assets
- name: Design Studio API
tags:
- Folders
- Components
- Emails
- Email link and publish
- Email testing
- SMS
- SMS link and publish
x-provenance:
method: harvested
publisher: Customer.io
source: https://docs.customer.io/openapi.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)