Customer.io
v1.0.0
OpenAPI 3.1.0

Connect a collection source

US region

Client Libraries
Shell Curl

Connect a collection source

​

Connect a bucket in Amazon S3, Google Cloud Storage, or Azure Blob Storage so that you can load files from it into your collections. After you connect a source, send its id and a file path to write to a collection, or sync a collection to load new files from a folder automatically.

Your credentials need permission to list and read the bucket:

  • S3: s3:ListBucket and s3:GetObject.
  • Google Cloud Storage: the Storage Object Viewer role.
  • Azure: a container SAS URL that grants read and list (sp=rl).

Before Customer.io saves the source, it lists the bucket under your prefix and reads the first file it finds. If the bucket has no files under the prefix yet, Customer.io can only check that your credentials list the bucket. Customer.io encrypts your credentials and never returns them.

Body
application/json
    • bucket
      Type: string
      required

      The name of your S3 bucket.

    • credentials
      Type: object
      required
    • name
      Type: string
      required

      A name that helps you recognize the source.

    • provider
      enum
      const:  
      s3
      required
      values
      • s3
    • region
      Type: string
      required

      The AWS region of your bucket.

    • prefix
      Type: string

      A folder in the bucket, like imports. When you set a prefix, Customer.io only reads files within it, and a write request's path is relative to it. Leave it out to read the whole bucket.

Responses
  • application/json
  • 400

    Your plan doesn't include collections.

  • 422

    Customer.io couldn't use the source. If your credentials are wrong, the error tells you whether Customer.io couldn't list the bucket or could list it but couldn't read its files.

  • application/json
Request Example for post/v1/collections/sources
{
  "bucket": "acme-exports",
  "credentials": {
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  },
  "name": "exports",
  "provider": "s3",
  "region": "us-east-1",
  "prefix": "imports"
}

{
  "source": {
    "bucket": "acme-exports",
    "created_at": "2026-11-02T15:31:31Z",
    "id": "01JD8X4Q6R2W7N3K5M9P1T0VZC",
    "name": "exports",
    "prefix": "imports",
    "provider": "s3",
    "region": "us-east-1",
    "updated_at": "2026-11-02T15:31:31Z"
  }
}

Customer.io read your bucket and saved the source.