> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/imports.md).

# Imports

CSV contact imports — history, contacts and the per-file segment.

## GET /imports

> Upload History — past CSV imports, newest first.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Imports","description":"CSV contact imports — history, contacts and the per-file segment."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Import":{"type":"object","description":"One CSV import, as it appears in the dashboard's Upload History.","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["import"]},"filename":{"type":"string","nullable":true},"status":{"type":"string","enum":["initializing","pending","completed","completed_with_errors","failed"],"description":"`completed_with_errors` = finished with some rows failed (`failed` > 0); stored as `completed` so the dashboard's Upload History shows it. `failed` = no row imported."},"total":{"type":"integer","description":"Rows found in the file."},"imported":{"type":"integer","description":"Contacts created or updated."},"failed":{"type":"integer","description":"Rows that could not be imported; see `errors`."},"unique_code":{"type":"integer","nullable":true,"description":"The import's code, stamped onto each contact as `csv_unique_code_array` and matched by the segment."},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"The dynamic segment holding exactly this file's contacts."},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true},"uploaded_by":{"type":"string","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"errors":{"type":"array","description":"Per-row failures. Only on the create response.","items":{"type":"object","additionalProperties":true}},"contact_ids":{"type":"array","description":"The contacts imported. Only on the create response.","items":{"$ref":"#/components/schemas/ContactId"}}},"required":["id","object","status"]},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"}}},"paths":{"/imports":{"get":{"tags":["Imports"],"operationId":"listImports","summary":"Upload History — past CSV imports, newest first.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Past imports.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Import"}}}}]}}}}}}}}}
```

## Import contacts from a CSV.

> Does what the dashboard's CSV upload screen does, so an import made here is indistinguishable from one made in the UI:\
> \
> 1\. contacts are upserted: matched on \`match\_on\` (default \`email\`) first, then — as the dashboard import does — by member id, phone and email in turn, whichever the row carries (phone/email legs also require the first name when the row has one). Deleted contacts never match;\
> 2\. the import appears in \*\*Upload History\*\*;\
> 3\. a dynamic segment \`Segment - \<filename> - \<code>\` is created holding exactly the contacts from this file.\
> \
> That segment is the useful part — it is how you then message or enrol just this batch. Every contact is stamped with the import's code, and the stamp is \*\*appended\*\*, so a contact appearing in several imports stays in all of their segments.\
> \
> Pass the file contents as \`csv\` (first line must be a header row) or pre-parsed \`rows\`. Recognized headers — email, phone, first/last name, external\_id, timezone, locale, date\_of\_birth, in several spellings — become contact fields; \`source\` → the contact's source (default \`csv\`, as the dashboard writes), \`location\` → its location, \`member\_id\` → its member id (\`user\_id\`, and \`data.member\_id\`), \`tags\` (comma-separated) → CRM tags. Every other column is kept as a custom field, coerced to its registered type, so nothing is silently dropped. New contacts count toward the workroom's contact total, and the import's segment gets its contact count (\`size\`) straight away, computed with the segment engine — membership itself is still computed by the dashboard the first time a campaign or flow uses the segment. Max 10,000 rows; split larger files.\
> \
> Imports exactly the CSV content supplied. An omitted workroom imports every contact into the account default.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Imports","description":"CSV contact imports — history, contacts and the per-file segment."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (≤255 chars) chosen by the client. Replays with the same key + same body return the cached response. Replays with the same key + different body return 409 `idempotency_conflict`. Required on messaging sends and bulk operations; recommended elsewhere.\n","schema":{"type":"string","maxLength":255}}},"schemas":{"ImportCreate":{"type":"object","anyOf":[{"required":["csv"]},{"required":["rows"]}],"properties":{"filename":{"type":"string","description":"Shown in Upload History and used to name the segment. Use the real file name; defaults to \"import.csv\"."},"csv":{"type":"string","description":"The file contents. The first line MUST be a header row naming the columns. A UTF-8 BOM is tolerated."},"rows":{"type":"array","description":"Pre-parsed rows, as objects keyed by column name. Use instead of `csv` when you already have structured data.","items":{"type":"object","additionalProperties":true}},"match_on":{"type":"string","enum":["email","phone","external_id"],"default":"email","description":"Which field identifies an existing contact, so the import updates rather than duplicates."},"create_segment":{"type":"boolean","default":true,"description":"Leave on unless the user explicitly does not want a segment — it is the only handle on \"the contacts from this file\"."},"segment_name":{"type":"string","description":"Overrides the default `Segment - <filename> - <code>`."}}},"Import":{"type":"object","description":"One CSV import, as it appears in the dashboard's Upload History.","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["import"]},"filename":{"type":"string","nullable":true},"status":{"type":"string","enum":["initializing","pending","completed","completed_with_errors","failed"],"description":"`completed_with_errors` = finished with some rows failed (`failed` > 0); stored as `completed` so the dashboard's Upload History shows it. `failed` = no row imported."},"total":{"type":"integer","description":"Rows found in the file."},"imported":{"type":"integer","description":"Contacts created or updated."},"failed":{"type":"integer","description":"Rows that could not be imported; see `errors`."},"unique_code":{"type":"integer","nullable":true,"description":"The import's code, stamped onto each contact as `csv_unique_code_array` and matched by the segment."},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"The dynamic segment holding exactly this file's contacts."},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true},"uploaded_by":{"type":"string","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"errors":{"type":"array","description":"Per-row failures. Only on the create response.","items":{"type":"object","additionalProperties":true}},"contact_ids":{"type":"array","description":"The contacts imported. Only on the create response.","items":{"$ref":"#/components/schemas/ContactId"}}},"required":["id","object","status"]},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"}}},"paths":{"/imports":{"post":{"tags":["Imports"],"operationId":"createImport","summary":"Import contacts from a CSV.","description":"Does what the dashboard's CSV upload screen does, so an import made here is indistinguishable from one made in the UI:\n\n1. contacts are upserted: matched on `match_on` (default `email`) first, then — as the dashboard import does — by member id, phone and email in turn, whichever the row carries (phone/email legs also require the first name when the row has one). Deleted contacts never match;\n2. the import appears in **Upload History**;\n3. a dynamic segment `Segment - <filename> - <code>` is created holding exactly the contacts from this file.\n\nThat segment is the useful part — it is how you then message or enrol just this batch. Every contact is stamped with the import's code, and the stamp is **appended**, so a contact appearing in several imports stays in all of their segments.\n\nPass the file contents as `csv` (first line must be a header row) or pre-parsed `rows`. Recognized headers — email, phone, first/last name, external_id, timezone, locale, date_of_birth, in several spellings — become contact fields; `source` → the contact's source (default `csv`, as the dashboard writes), `location` → its location, `member_id` → its member id (`user_id`, and `data.member_id`), `tags` (comma-separated) → CRM tags. Every other column is kept as a custom field, coerced to its registered type, so nothing is silently dropped. New contacts count toward the workroom's contact total, and the import's segment gets its contact count (`size`) straight away, computed with the segment engine — membership itself is still computed by the dashboard the first time a campaign or flow uses the segment. Max 10,000 rows; split larger files.\n\nImports exactly the CSV content supplied. An omitted workroom imports every contact into the account default.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportCreate"}}}},"responses":{"201":{"description":"The import, with the segment it created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}},"422":{"description":"The CSV could not be used — empty, header-only, or too many rows."}}}}}}
```

## GET /imports/{id}

> Retrieve one import.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Imports","description":"CSV contact imports — history, contacts and the per-file segment."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"Import":{"type":"object","description":"One CSV import, as it appears in the dashboard's Upload History.","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["import"]},"filename":{"type":"string","nullable":true},"status":{"type":"string","enum":["initializing","pending","completed","completed_with_errors","failed"],"description":"`completed_with_errors` = finished with some rows failed (`failed` > 0); stored as `completed` so the dashboard's Upload History shows it. `failed` = no row imported."},"total":{"type":"integer","description":"Rows found in the file."},"imported":{"type":"integer","description":"Contacts created or updated."},"failed":{"type":"integer","description":"Rows that could not be imported; see `errors`."},"unique_code":{"type":"integer","nullable":true,"description":"The import's code, stamped onto each contact as `csv_unique_code_array` and matched by the segment."},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"The dynamic segment holding exactly this file's contacts."},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true},"uploaded_by":{"type":"string","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"errors":{"type":"array","description":"Per-row failures. Only on the create response.","items":{"type":"object","additionalProperties":true}},"contact_ids":{"type":"array","description":"The contacts imported. Only on the create response.","items":{"$ref":"#/components/schemas/ContactId"}}},"required":["id","object","status"]},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"}}},"paths":{"/imports/{id}":{"get":{"tags":["Imports"],"operationId":"retrieveImport","summary":"Retrieve one import.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"}],"responses":{"200":{"description":"The import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Import"}}}}}}}}}
```

## Remove an import from Upload History.

> Deletes the history entry \*\*only\*\*. The contacts the import created and the segment it created are deliberately left in place: the contacts are real people who may already have been messaged, and the segment may already be wired into a flow or campaign.\
> \
> This is bookkeeping, not an undo — there is no safe automatic undo for an import. To reverse one, delete the segment and the contacts explicitly.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Imports","description":"CSV contact imports — history, contacts and the per-file segment."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}}},"paths":{"/imports/{id}":{"delete":{"tags":["Imports"],"operationId":"deleteImport","summary":"Remove an import from Upload History.","description":"Deletes the history entry **only**. The contacts the import created and the segment it created are deliberately left in place: the contacts are real people who may already have been messaged, and the segment may already be wired into a flow or campaign.\n\nThis is bookkeeping, not an undo — there is no safe automatic undo for an import. To reverse one, delete the segment and the contacts explicitly.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"}],"responses":{"204":{"description":"Removed from history."},"404":{"description":"No such import in this account."}}}}}}
```
