Start a CSV Upload

Contact Import Upload Init

curl --request POST \
  --url https://api.example.com/contacts/import/upload-init \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "<string>",
  "size": 123
}
'

import requests

url = "https://api.example.com/contacts/import/upload-init"

payload = {
    "filename": "<string>",
    "size": 123
}
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({filename: '<string>', size: 123})
};

fetch('https://api.example.com/contacts/import/upload-init', 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.example.com/contacts/import/upload-init",
  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([
    'filename' => '<string>',
    'size' => 123
  ]),
  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.example.com/contacts/import/upload-init"

	payload := strings.NewReader("{\n  \"filename\": \"<string>\",\n  \"size\": 123\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.example.com/contacts/import/upload-init")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"<string>\",\n  \"size\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/contacts/import/upload-init")

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  \"filename\": \"<string>\",\n  \"size\": 123\n}"

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

{}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

contacts

import

upload-init

Contact Import Upload Init

curl --request POST \
  --url https://api.example.com/contacts/import/upload-init \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "<string>",
  "size": 123
}
'

import requests

url = "https://api.example.com/contacts/import/upload-init"

payload = {
    "filename": "<string>",
    "size": 123
}
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({filename: '<string>', size: 123})
};

fetch('https://api.example.com/contacts/import/upload-init', 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.example.com/contacts/import/upload-init",
  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([
    'filename' => '<string>',
    'size' => 123
  ]),
  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.example.com/contacts/import/upload-init"

	payload := strings.NewReader("{\n  \"filename\": \"<string>\",\n  \"size\": 123\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.example.com/contacts/import/upload-init")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"<string>\",\n  \"size\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/contacts/import/upload-init")

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  \"filename\": \"<string>\",\n  \"size\": 123\n}"

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

{}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Importing contacts is a 3-step flow so a large file is uploaded directly to storage rather than proxied through an API request body, and so mapping columns is a separate, correctable step from committing rows: upload-init (this endpoint — get a presigned URL, PUT the file directly to S3) → preview (see detected columns + a sample) → import (confirm the mapping, get an import_id back immediately, poll for the result). All three calls share a 15 MB file-size cap and require CRM manage scope. Issues a presigned S3 PUT URL scoped to the caller’s organization (object key is {org_id}/imports/{random}/{sanitized filename}). The client uploads the raw CSV bytes directly to upload_url with a text/csv content type, then passes the returned s3_key to preview/import. A client that understates the declared size isn’t blocked here — it’s still caught later, when Preview reads the actual object back.

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Response

Field	Type	Description
`upload_url`	`string`	Presigned S3 PUT URL, expires in 15 minutes.
`s3_key`	`string`	Pass this to Preview and Import.

Errors

Status	Cause
`413`	Declared `size` exceeds 15 MB.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request a presigned S3 PUT URL for a contact-import CSV.

filename

string

required

Original CSV filename; sanitized into the S3 key.

Minimum string length: 1

size

integer | null

Declared file size in bytes, checked against the 15 MB cap before issuing the URL.

Response

Successful Response

The response is of type Response Contact Import Upload Init Contacts Import Upload Init Post · object.

Contacts

Deals

Accounts

Activities

Tags

Files

Folders

Notifications

Reports

PATs

Integrations

AI

Analytics Assistant

Feedback

Customer Intelligence

Outreach

AnyCard

AnyCard Events

AnyCard Share Links

Public Media

Account Readiness

Service Health

Auth

Response

Errors

Authorizations

Body

Response

​Auth

​Response

​Errors

Authorizations

Body

Response

Auth

Response

Errors