Skip to content
Vocapable Developers

Import contacts from a CSV

POST
/v1/contact-imports
curl --request POST \
  --url https://api.vocapable.com/v1/contact-imports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "file_name": "example", "content": "example", "column_mapping": { "additionalProperty": "phone_e164" }, "consent_attestation": { "signer_name": "example", "signer_title": "example", "affirmation": "example", "consent_basis": "pewc" }, "target_list_id": "example", "list_name": "example", "on_duplicate": "reject" }'

Land a CSV in a contact list and report every row that could not be taken.

Answered at 202 with the documented poll contract on GET /contact-imports/{id}; the P1 import runs inside this request, so the job is already terminal when it answers.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
Any of:
string

Unique key for this request, so a retry replays the original result instead of repeating the work. Stored for 24 hours; a replayed response carries Idempotent-Replay: true. A UUID is the documented shape.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
ContactImportRequest

An import submission.

The CSV arrives as a text field rather than multipart/form-data: multipart needs python-multipart, which is not a workspace dependency. The parser takes the file’s text either way, so the wire shape can change without touching it.

object
file_name
required
File Name
string
>= 1 characters <= 255 characters
content
required
Content
string
>= 1 characters
column_mapping
required
Column Mapping
object
key
additional properties
string
Allowed values: phone_e164 first_name last_name company title email timezone
consent_attestation
required
ConsentAttestationInput

What the tenant affirms about the list they are uploading.

Required on every import: the affirmation is the evidence linking each later dial to a named human who declared the consent basis (docs/03-domain-model.md §Audience).

object
signer_name
required
Signer Name
string
>= 1 characters <= 200 characters
signer_title
required
Signer Title
string
>= 1 characters <= 200 characters
affirmation
required
Affirmation
string
>= 1 characters
consent_basis
required
ConsentBasis

CANON fact 18 - the four consent classes (docs/07-compliance.md §consent).

string
Allowed values: pewc pec ebr transactional
target_list_id
Any of:
string
list_name
Any of:
string
<= 200 characters
on_duplicate
On Duplicate
string
default: reject
Allowed values: reject skip update

Responses

Section titled “Responses”

202

Section titled “202”

Successful Response

Media typeapplication/json
ImportJob
object
id
required
Id
string
status
required
JobStatus

Lifecycle shared by the async import and export jobs.

string
Allowed values: queued running completed failed
file_uri
required
File Uri
string
column_mapping
Column Mapping
object
key
additional properties
string
target_list_id
Any of:
string
consent_attestation
required
ConsentAttestation

The stored attestation. signer_ip and signed_at are stamped by the API - a client-supplied timestamp is a claim, not evidence.

object
signer_name
required
Signer Name
string
>= 1 characters <= 200 characters
signer_title
required
Signer Title
string
>= 1 characters <= 200 characters
affirmation
required
Affirmation
string
>= 1 characters
consent_basis
required
ConsentBasis

CANON fact 18 - the four consent classes (docs/07-compliance.md §consent).

string
Allowed values: pewc pec ebr transactional
signer_ip
Any of:
string
signed_at
required
Signed At
string format: date-time
rows_accepted
required
Rows Accepted
integer
rows_rejected
required
Rows Rejected
integer
rows_skipped
Rows Skipped
integer
0
on_duplicate
On Duplicate
string
default: reject
Allowed values: reject skip update
created_at
required
Created At
string format: date-time
updated_at
required
Updated At
string format: date-time
Example
{
  "status": "queued",
  "consent_attestation": {
    "consent_basis": "pewc"
  },
  "rows_skipped": 0,
  "on_duplicate": "reject"
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}