Import mappings

Generated from DialerDigital/core commit 0fc18008b3c8 — spec openapi/dialer-v1.yaml v0.134.0. Do not edit by hand; see How this reference is built. Download the OpenAPI spec.

Español

CSV import templates (column -> field mapping and parse options), versioned append-only per tenant.

Endpoints

Method	Path	Summary
GET	/v1/import-mappings	The tenant's CSV import templates, each with its current version
POST	/v1/import-mappings	Create an import template (version 1)
GET	/v1/import-mappings/{id}	One import template, at its current version
PATCH	/v1/import-mappings/{id}	Rename a template, or edit it into a NEW version
DELETE	/v1/import-mappings/{id}	Archive a template
GET	/v1/import-mappings/{id}/versions	Every version of a template, oldest first
GET	/v1/import-mappings/{id}/versions/{version}	One version of a template
GET	/v1/import-mappings/{id}/uses	The imports that used a template, newest first

The tenant's CSV import templates, each with its current version

GET /v1/import-mappings

By name, the live ones; ?include_archived=true adds the archived. Each template comes with its CURRENT version. Capped at 2 000.

Parameters

Name	In	Type	Required	Description
include_archived	query	boolean	no

Responses

200

The templates.

Field	Type	Required	Description
import_mappings	array of ImportMapping	yes
import_mappings[].id	string (uuid)	yes
import_mappings[].tenant_id	string (uuid)	no
import_mappings[].name	string	yes
import_mappings[].archived	boolean	yes
import_mappings[].version	integer	yes	The current version.
import_mappings[].mapping	array of object	yes	ORDERED list of CSV column -> target field. The order is the file's, because a template is applied to a file whose header signature (its headers, in order) equals the template's.
import_mappings[].mapping[].column	string	yes	The CSV header, as the file spells it.
import_mappings[].mapping[].field	string	yes	The target field, or skip. One optional group.name dot (contact.phone_e164).
import_mappings[].options	object (ImportMappingOptions)	yes	Parse options. Unknown keys are refused.
import_mappings[].options.separator	comma · semicolon · tab	no
import_mappings[].options.default_currency	string	no
import_mappings[].version_created_at	string (date-time)	no
import_mappings[].created_at	string (date-time)	no
import_mappings[].updated_at	string (date-time)	no

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

Create an import template (version 1)

POST /v1/import-mappings

name is trimmed, not blank, at most 200 characters and unique among the tenant's LIVE templates (409). mapping is an ORDERED list of {column, field}: column is the CSV header as the file spells it (trimmed, at most 200 characters; two entries may not differ only by case or spaces), field the target (a-z, digits and _, at most 64, with one optional group.name dot). The server checks the SHAPE of field, not a closed vocabulary: each consumer of a template fails closed on a field it does not know. At least one entry must map to a field other than skip. options accepts separator (comma, semicolon, tab; default comma) and default_currency (three uppercase letters); any other key is refused. A tenant holds at most 500 live templates (422).

Request body (JSON, required)

Field	Type	Required	Description
name	string	yes
mapping	array of object	yes	ORDERED list of CSV column -> target field. The order is the file's, because a template is applied to a file whose header signature (its headers, in order) equals the template's.
mapping[].column	string	yes	The CSV header, as the file spells it.
mapping[].field	string	yes	The target field, or skip. One optional group.name dot (contact.phone_e164).
options	object (ImportMappingOptions)	no	Parse options. Unknown keys are refused.
options.separator	comma · semicolon · tab	no
options.default_currency	string	no

{
  "name": "Cartera Q3 — export CMS",
  "mapping": [
    {
      "column": "Cuenta",
      "field": "external_ref"
    },
    {
      "column": "Teléfono",
      "field": "phone_primary"
    },
    {
      "column": "Notas",
      "field": "skip"
    }
  ],
  "options": {
    "separator": "semicolon",
    "default_currency": "USD"
  }
}

Responses

201

The template, at version 1.

Field	Type	Required	Description
import_mapping	object (ImportMapping)	yes	A template: its header and its CURRENT version.
import_mapping.id	string (uuid)	yes
import_mapping.tenant_id	string (uuid)	no
import_mapping.name	string	yes
import_mapping.archived	boolean	yes
import_mapping.version	integer	yes	The current version.
import_mapping.mapping	array of object	yes	ORDERED list of CSV column -> target field. The order is the file's, because a template is applied to a file whose header signature (its headers, in order) equals the template's.
import_mapping.mapping[].column	string	yes	The CSV header, as the file spells it.
import_mapping.mapping[].field	string	yes	The target field, or skip. One optional group.name dot (contact.phone_e164).
import_mapping.options	object (ImportMappingOptions)	yes	Parse options. Unknown keys are refused.
import_mapping.options.separator	comma · semicolon · tab	no
import_mapping.options.default_currency	string	no
import_mapping.version_created_at	string (date-time)	no
import_mapping.created_at	string (date-time)	no
import_mapping.updated_at	string (date-time)	no

400 — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

409 — Conflict

Invalid state transition, uniqueness conflict, or a seat that is busy/reserved.

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

422 — Unprocessable

Shape is fine, semantics are not (broken domain rule).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

One import template, at its current version

GET /v1/import-mappings/{id}

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.

Responses

200

The template (archived ones too, flagged archived).

Field	Type	Required	Description
import_mapping	object (ImportMapping)	yes	A template: its header and its CURRENT version.
import_mapping.id	string (uuid)	yes
import_mapping.tenant_id	string (uuid)	no
import_mapping.name	string	yes
import_mapping.archived	boolean	yes
import_mapping.version	integer	yes	The current version.
import_mapping.mapping	array of object	yes	ORDERED list of CSV column -> target field. The order is the file's, because a template is applied to a file whose header signature (its headers, in order) equals the template's.
import_mapping.mapping[].column	string	yes	The CSV header, as the file spells it.
import_mapping.mapping[].field	string	yes	The target field, or skip. One optional group.name dot (contact.phone_e164).
import_mapping.options	object (ImportMappingOptions)	yes	Parse options. Unknown keys are refused.
import_mapping.options.separator	comma · semicolon · tab	no
import_mapping.options.default_currency	string	no
import_mapping.version_created_at	string (date-time)	no
import_mapping.created_at	string (date-time)	no
import_mapping.updated_at	string (date-time)	no

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

Rename a template, or edit it into a NEW version

PATCH /v1/import-mappings/{id}

Send at least one of name, mapping, options. A rename changes the header only. Changing mapping or options appends version n+1 (the one omitted is carried over from the current) and leaves version n exactly as it was: an import may have used it. An edit that changes nothing writes no version. base_version is optional and, when sent, must be the current version — otherwise 409 and nothing is written, so two people editing the same template do not overwrite each other unnoticed. An archived template cannot be edited (409); a template holds at most 1 000 versions (422).

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.

Request body (JSON, required)

Field	Type	Required	Description
name	string	no
mapping	array of object	no	ORDERED list of CSV column -> target field. The order is the file's, because a template is applied to a file whose header signature (its headers, in order) equals the template's.
mapping[].column	string	yes	The CSV header, as the file spells it.
mapping[].field	string	yes	The target field, or skip. One optional group.name dot (contact.phone_e164).
options	object (ImportMappingOptions)	no	Parse options. Unknown keys are refused.
options.separator	comma · semicolon · tab	no
options.default_currency	string	no
base_version	integer	no

{
  "base_version": 1,
  "options": {
    "separator": "comma"
  }
}

Responses

200

The template, at its current version after the edit.

Field	Type	Required	Description
import_mapping	object (ImportMapping)	yes	A template: its header and its CURRENT version.
import_mapping.id	string (uuid)	yes
import_mapping.tenant_id	string (uuid)	no
import_mapping.name	string	yes
import_mapping.archived	boolean	yes
import_mapping.version	integer	yes	The current version.
import_mapping.mapping	array of object	yes	ORDERED list of CSV column -> target field. The order is the file's, because a template is applied to a file whose header signature (its headers, in order) equals the template's.
import_mapping.mapping[].column	string	yes	The CSV header, as the file spells it.
import_mapping.mapping[].field	string	yes	The target field, or skip. One optional group.name dot (contact.phone_e164).
import_mapping.options	object (ImportMappingOptions)	yes	Parse options. Unknown keys are refused.
import_mapping.options.separator	comma · semicolon · tab	no
import_mapping.options.default_currency	string	no
import_mapping.version_created_at	string (date-time)	no
import_mapping.created_at	string (date-time)	no
import_mapping.updated_at	string (date-time)	no

400 — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

409 — Conflict

Invalid state transition, uniqueness conflict, or a seat that is busy/reserved.

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

422 — Unprocessable

Shape is fine, semantics are not (broken domain rule).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

Archive a template

DELETE /v1/import-mappings/{id}

Templates are never deleted: the versions an import used are evidence. Archiving frees the name for a new template and takes the template out of the default list; it can no longer be edited or named by an import. Idempotent.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.

Responses

204

The template is archived.

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

Every version of a template, oldest first

GET /v1/import-mappings/{id}/versions

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.

Responses

200

The versions (capped at 1 000).

Field	Type	Required	Description
versions	array of ImportMappingVersion	yes
versions[].mapping_id	string (uuid)	yes
versions[].version	integer	yes
versions[].mapping	array of object	yes	ORDERED list of CSV column -> target field. The order is the file's, because a template is applied to a file whose header signature (its headers, in order) equals the template's.
versions[].mapping[].column	string	yes	The CSV header, as the file spells it.
versions[].mapping[].field	string	yes	The target field, or skip. One optional group.name dot (contact.phone_e164).
versions[].options	object (ImportMappingOptions)	yes	Parse options. Unknown keys are refused.
versions[].options.separator	comma · semicolon · tab	no
versions[].options.default_currency	string	no
versions[].created_at	string (date-time)	no

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

One version of a template

GET /v1/import-mappings/{id}/versions/{version}

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.
version	path	integer	yes	The version number (>= 1). Unknown, malformed or another tenant's reads as 404.

Responses

200

The version, exactly as it was written.

Field	Type	Required	Description
version	object (ImportMappingVersion)	yes	One immutable version of a template.
version.mapping_id	string (uuid)	yes
version.version	integer	yes
version.mapping	array of object	yes	ORDERED list of CSV column -> target field. The order is the file's, because a template is applied to a file whose header signature (its headers, in order) equals the template's.
version.mapping[].column	string	yes	The CSV header, as the file spells it.
version.mapping[].field	string	yes	The target field, or skip. One optional group.name dot (contact.phone_e164).
version.options	object (ImportMappingOptions)	yes	Parse options. Unknown keys are refused.
version.options.separator	comma · semicolon · tab	no
version.options.default_currency	string	no
version.created_at	string (date-time)	no

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

The imports that used a template, newest first

GET /v1/import-mappings/{id}/uses

One row per import that named the template (?mapping_id= on POST /v1/debts/import or POST /v1/debt-lists/{id}/import): the version it used and how many items went in and failed. Append-only. Capped at 200.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.

Responses

200

The uses.

Field	Type	Required	Description
uses	array of ImportMappingUse	yes
uses[].id	string (uuid)	yes
uses[].mapping_id	string (uuid)	yes
uses[].version	integer	yes
uses[].list_id	string (uuid) | null	no	The list, when the import went through /v1/debt-lists/{id}/import.
uses[].imported	integer	yes
uses[].failed	integer	yes	Number of items that failed.
uses[].created_at	string (date-time)	no

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}