> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.jelliu.co/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.jelliu.co/_mcp/server. # Preview a CSV import POST https://api.jelliu.co/api/campaigns/{campaignId}/contacts/upload-preview Content-Type: multipart/form-data Step 1 of the CSV import. Upload the file as `multipart/form-data` (field `file`). The response has the headers, the first 10 rows, a proposed column mapping, validation stats and the file's SHA-256 `fileHash`. Nothing is stored. Review or adjust the mapping, then send the **same file** with it to `POST /api/campaigns/{campaignId}/contacts/upload-confirm`. **File rules.** The name must end in `.csv` and the part's MIME type must be `text/csv`, `application/csv` or `text/plain`. Maximum 10 MB, comma-separated, first row = headers. Encoding UTF-8 (a BOM is fine) or UTF-16 with BOM; other encodings are refused, so use "CSV UTF-8" when saving from Excel. XLSX, XLS, PDF and other binary files are refused. Each field is limited to 1 MB and each row to 500 columns. Blank lines are ignored. **Detected mapping.** Headers are matched case-insensitively. Columns containing `whatsapp`/`wa` map to `whatsappNumber`, `phone`/`tel`/`mobile`/`celular`/`telefono`/`numero` to `phoneNumber`, `email`/`correo`/`mail` to `email`, and `name`/`nombre`/`contact` to `name`. Otherwise the sample values decide (mostly phone-shaped, or mostly containing `@`). Each field is claimed by the **first** matching column; later matches and everything else become `metadata`. **Stats** cover only the first 1,000 rows. A phone is valid there with 7 to 15 digits after removing spaces, dashes and parentheses; confirm applies the stricter rules described on that endpoint. `errors` holds up to 100 entries. Preview cells starting with `=`, `+`, `-` or `@` are prefixed with `'` so they cannot run as spreadsheet formulas; stored values are not changed. The campaign itself is not looked up here: an unknown `campaignId` still gets a preview. **Idempotency.** Safe to retry: nothing is written, and the same file always returns the same `fileHash`. **Access** * **Required scope:** `write` (or `full`). * **Rate limit:** Contacts import — 5 requests/min per workspace, shared by every route under `/api/campaigns/{campaignId}/contacts`, on top of the general API limit. See [Rate limits](/rate-limits). * **Plan:** Refused with 403 `BILLING_ERROR` when the workspace contact cap is already reached (Starter 500, Growth 2,000, Business 20,000). Reference: https://developer.jelliu.co/api-reference/contacts/post-campaigns-by-campaign-id-contacts-upload-preview ## Authentication - `Authorization` header (bearer token, required) — Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication). ## Request ### Path parameters - `campaignId` (string, required) — UUID of the campaign the file is meant for. Only its format is checked here (400 if not a UUID); it is not looked up. ### Body (multipart/form-data) This endpoint expects a multipart form containing a file. - `file` (file, required) — The CSV file (form field `file`, `.csv`, max 10 MB). ## Response ### 200 Parsed preview. - `success` (true, required) — Always `true` on 200. - `data` (object, required) - `headers` (list of string, required) — Header row, trimmed, in file order. - `previewRows` (list of map from string to string, required) — First 10 data rows keyed by header, with formula-like cells prefixed by `'`. - `detectedMapping` (map from string to enum, required) — Proposed target field for every header. Send it back (edited or not) as `mapping` to upload-confirm. - Allowed values: `phoneNumber`, `name`, `email`, `whatsappNumber`, `metadata`, `ignore` - `stats` (object, required) — Validation over the first 1,000 data rows using the detected mapping. - `totalRows` (integer, optional) — Data rows validated (at most 1000). - `validRows` (integer, optional) — Rows with no validation error. - `invalidRows` (integer, optional) — Rows with at least one error. - `duplicateRows` (integer, optional) — Rows repeating an earlier row's phone (or email when there is no phone). They are still counted as valid and collapse into one contact on import. - `errors` (list of object, optional) — Up to 100 row-level problems. - `row` (integer, optional) — Line number in the file, counting the header as row 1 and skipping blank lines. - `field` (string, optional) — The CSV header of the offending column, or `-` when no identifier was found. - `message` (string, optional) — What is wrong. - `fileHash` (string, required) — SHA-256 of the uploaded bytes, lowercase hex. Required by upload-confirm. ## Errors ### 400 Bad Request Error No file, not a CSV, too large, binary, not UTF-8, or empty. - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ### 401 Unauthorized Error No usable credential. Either the `Authorization` header is missing or is not a well-formed `Bearer jl_…` key, or the key is unknown, revoked or expired. Do not retry with the same key. See [Authentication](/authentication#401-unauthorized). - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ### 403 Forbidden Error The workspace contact cap is already reached, or the API key lacks the `write` scope. - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ### 429 Too Many Requests Error The contacts-import limit (5/min) or the general API limit was exceeded. - `error` (object, required) — The error object. Always has `code` and `message`. - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors). - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice. - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields). - Field map - `formErrors` (list of string, optional) - `fieldErrors` (map from string to list of string, optional) - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates). ## Examples ### Contacts_postCampaignsByCampaignIdContactsUploadPreview_example **Request** ```json {} ``` **Response** ```json { "success": true, "data": { "headers": [ "telefono", "nombre", "correo", "plan" ], "previewRows": [ { "correo": "maria.gomez@example.com", "nombre": "María Gómez", "plan": "prepago", "telefono": "+573001234567" }, { "correo": "carlos.perez@example.com", "nombre": "Carlos Pérez", "plan": "postpago", "telefono": "+573157654321" } ], "detectedMapping": { "correo": "email", "nombre": "name", "plan": "metadata", "telefono": "phoneNumber" }, "stats": { "totalRows": 250, "validRows": 248, "invalidRows": 2, "duplicateRows": 3, "errors": [ { "row": 17, "field": "telefono", "message": "Invalid phone number: \"300-12\"" }, { "row": 88, "field": "-", "message": "No phone number or email found" } ] }, "fileHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } } ``` **SDK Code** ```python Contacts_postCampaignsByCampaignIdContactsUploadPreview_example import requests url = "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview" headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers) print(response.json()) ``` ```javascript Contacts_postCampaignsByCampaignIdContactsUploadPreview_example const url = 'https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Contacts_postCampaignsByCampaignIdContactsUploadPreview_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Contacts_postCampaignsByCampaignIdContactsUploadPreview_example require 'uri' require 'net/http' url = URI("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Contacts_postCampaignsByCampaignIdContactsUploadPreview_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview") .header("Authorization", "Bearer ") .asString(); ``` ```php Contacts_postCampaignsByCampaignIdContactsUploadPreview_example request('POST', 'https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Contacts_postCampaignsByCampaignIdContactsUploadPreview_example using RestSharp; var client = new RestClient("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Contacts_postCampaignsByCampaignIdContactsUploadPreview_example import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### A small CSV with Spanish headers **Request** ```json { "file": "" } ``` **Response** ```json { "success": true, "data": { "headers": [ "telefono", "nombre", "correo", "plan" ], "previewRows": [ { "correo": "maria.gomez@example.com", "nombre": "María Gómez", "plan": "prepago", "telefono": "+573001234567" }, { "correo": "carlos.perez@example.com", "nombre": "Carlos Pérez", "plan": "postpago", "telefono": "+573157654321" } ], "detectedMapping": { "correo": "email", "nombre": "name", "plan": "metadata", "telefono": "phoneNumber" }, "stats": { "totalRows": 250, "validRows": 248, "invalidRows": 2, "duplicateRows": 3, "errors": [ { "row": 17, "field": "telefono", "message": "Invalid phone number: \"300-12\"" }, { "row": 88, "field": "-", "message": "No phone number or email found" } ] }, "fileHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } } ``` **SDK Code** ```python A small CSV with Spanish headers import requests url = "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview" files = { "file": "open('telefono,nombre,correo,plan +573001234567,María Gómez,maria.gomez@example.com,prepago +573157654321,Carlos Pérez,carlos.perez@example.com,postpago ', 'rb')" } headers = {"Authorization": "Bearer "} response = requests.post(url, files=files, headers=headers) print(response.json()) ``` ```javascript A small CSV with Spanish headers const url = 'https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview'; const form = new FormData(); form.append('file', 'telefono,nombre,correo,plan +573001234567,María Gómez,maria.gomez@example.com,prepago +573157654321,Carlos Pérez,carlos.perez@example.com,postpago '); const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; options.body = form; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go A small CSV with Spanish headers package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview" payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"telefono,nombre,correo,plan\n+573001234567,María Gómez,maria.gomez@example.com,prepago\n+573157654321,Carlos Pérez,carlos.perez@example.com,postpago\n\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby A small CSV with Spanish headers require 'uri' require 'net/http' url = URI("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"telefono,nombre,correo,plan\n+573001234567,María Gómez,maria.gomez@example.com,prepago\n+573157654321,Carlos Pérez,carlos.perez@example.com,postpago\n\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n" response = http.request(request) puts response.read_body ``` ```java A small CSV with Spanish headers import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview") .header("Authorization", "Bearer ") .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"telefono,nombre,correo,plan\n+573001234567,María Gómez,maria.gomez@example.com,prepago\n+573157654321,Carlos Pérez,carlos.perez@example.com,postpago\n\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n") .asString(); ``` ```php A small CSV with Spanish headers request('POST', 'https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview', [ 'multipart' => [ [ 'name' => 'file', 'filename' => 'telefono,nombre,correo,plan +573001234567,María Gómez,maria.gomez@example.com,prepago +573157654321,Carlos Pérez,carlos.perez@example.com,postpago ', 'contents' => null ] ] 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp A small CSV with Spanish headers using RestSharp; var client = new RestClient("https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"telefono,nombre,correo,plan\n+573001234567,María Gómez,maria.gomez@example.com,prepago\n+573157654321,Carlos Pérez,carlos.perez@example.com,postpago\n\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift A small CSV with Spanish headers import Foundation let headers = ["Authorization": "Bearer "] let parameters = [ [ "name": "file", "fileName": "telefono,nombre,correo,plan +573001234567,María Gómez,maria.gomez@example.com,prepago +573157654321,Carlos Pérez,carlos.perez@example.com,postpago " ] ] let boundary = "---011000010111000001101001" var body = "" var error: NSError? = nil for param in parameters { let paramName = param["name"]! body += "--\(boundary)\r\n" body += "Content-Disposition:form-data; name=\"\(paramName)\"" if let filename = param["fileName"] { let contentType = param["content-type"]! let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8) if (error != nil) { print(error as Any) } body += "; filename=\"\(filename)\"\r\n" body += "Content-Type: \(contentType)\r\n\r\n" body += fileContent } else if let paramValue = param["value"] { body += "\r\n\r\n\(paramValue)" } } let request = NSMutableURLRequest(url: NSURL(string: "https://api.jelliu.co/api/campaigns/5b0c8f7e-2f4a-4d7e-9a53-0f6f2f3c1a10/contacts/upload-preview")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```