Import

Import ticket details, customers, or articles. Processes up to 500 records synchronously and supports merge strategies.

The Impor object

entityType string

Imported entity type: ticket, customer or article

total integer

Total records processed

created integer

Records created

updated integer

Records updated

skipped integer

Records skipped

warnings string[]

Rows saved with something missing or skipped as duplicates, each starting "Row N:"

Endpoints

POST Run Import GET List Import Logs

POST /api/v1/teams/{teamId}/import

Run Import

Import up to 500 records synchronously. A ticket brings its details, its requester (customer_email is found or created as a customer in the key's test or live mode) and its description as the first customer message. Replies, private notes and attachments are not migrated. A customer created without an email fails with a row error.

Request Body

resource string required

Resource type

records array required

Array of flat record objects or wrapped { data, action, existingId? } records. For ticket create/update records, nonempty arrays at messages, _messages, comments, audits, conversations, threads, _embedded.threads, conversation_parts, or conversation_parts.conversation_parts, on the record or its data object, cause HTTP 400 before any records in the request are written. A truthy source.body paired with an array at conversation_parts or conversation_parts.conversation_parts also causes HTTP 400, even if that array is empty. Empty history without this initial-message shape, customFields/metadata and wrapped records with action: "skip" are allowed.

mergeStrategy string

How to handle duplicates

Default: skip

Code Examples

bash

curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/import" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"resource":"customers","records":[{"name":"Jane","email":"jane@example.com"}],"mergeStrategy":"skip"}'

Responses

201 Import result

json

{
  "success": true,
  "data": {
    "object": "import_result",
    "logId": "550e8400-e29b-41d4-a716-446655440001",
    "entityType": "customer",
    "success": true,
    "total": 1,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "failed": 0,
    "createdIds": [
      {
        "rowIndex": 1,
        "id": "550e8400-e29b-41d4-a716-446655440002"
      }
    ],
    "durationMs": 10
  }
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

GET /api/v1/teams/{teamId}/import

List Import Logs

List import history logs.

Code Examples

bash

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/import" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Import logs

json

{
  "success": true,
  "data": [
    {
      "id": "imp_abc",
      "resource": "customers",
      "status": "completed",
      "totalRecords": 50,
      "created": 45,
      "createdAt": "2025-12-10T14:30:00Z"
    }
  ]
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}