> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesfinity.ai/llms.txt > Use this file to discover all available pages before exploring further. # List custom field mappings > Returns the team's custom field mappings: one record for each source (a CRM, or `csv` for CSV uploads) whose field mapping was saved in the dashboard's integration settings. Each entry in `fields` (contacts) and `lead_fields` (leads) ties a field in that source (`external_key`, `external_name`) to the name Salesfinity shows for it (`internal_name`). When contacts are imported from a CRM, each mapped field becomes a custom field on the contact whose `label` is the `internal_name`. The `custom_fields` you send to `POST /v1/contact-lists` and `POST /v1/contact-lists/{id}` are free text and are not checked against these mappings. Reuse an `internal_name` as the `label` to give an API-created contact the same field a CRM-imported one has. Not paginated. The array is empty when nothing is mapped. Records for some CRMs also carry `deal_fields`, `account_fields`, `deal_field_mapping` and `account_field_mapping`. Returns the custom field mappings your team saved in the dashboard's integration settings: one record per source, such as `hubspot`, `salesforce` or `csv`. The response is a plain array, not paginated, and empty when nothing is mapped. ### What a mapping does Each entry in `fields` (contacts) or `lead_fields` (leads) ties a field in the source to the name Salesfinity shows for it: | Key | Meaning | Example | | - | - | - | | `external_key` | The field's API name in the source | `account_tier` | | `external_name` | The field's display name in the source | `Account Tier` | | `internal_name` | The name Salesfinity shows | `Account tier` | | `type`, `field_type` | The field's data type and input type, as the source names them | `enumeration`, `select` | When contacts are imported from a CRM, each mapped field becomes a custom field on the contact, with `label` set to `internal_name`. Records for some CRMs also carry `deal_fields`, `account_fields`, `deal_field_mapping` and `account_field_mapping`, which set the deal and account fields shown for that CRM. ### Using mappings with contact lists The `custom_fields` on contacts you send to [Create a contact list](/api-reference/endpoint/create-list) and [Add a contact to a list](/api-reference/endpoint/add-contact) are free text: nothing checks them against these mappings. To give an API-created contact the same field a CRM import creates, use the mapping's `internal_name` as the `label`: ```json theme={"system"} { "type": "string", "label": "Account tier", "value": "Enterprise" } ``` ### Example ```bash theme={"system"} curl https://client-api.salesfinity.co/v1/custom-fields \ --header 'x-api-key: YOUR_API_KEY' ``` ```json theme={"system"} [ { "_id": "66e0f3a1b2c3d4e5f6a7b8c9", "source": "hubspot", "team": "64f1a2b3c4d5e6f7a8b9c0d1", "user": "680edc0d1504192884a148e0", "fields": [ { "_id": "66e0f3a1b2c3d4e5f6a7b8ca", "type": "enumeration", "field_type": "select", "internal_name": "Account tier", "external_key": "account_tier", "external_name": "Account Tier" } ], "lead_fields": [], "createdAt": "2026-09-14T09:20:11.204Z", "updatedAt": "2026-09-30T16:45:02.871Z", "__v": 0 } ] ``` ## OpenAPI ````yaml GET /v1/custom-fields openapi: 3.0.1 info: title: Salesfinity API description: >- The Salesfinity API is a JSON-over-HTTPS REST API for the Salesfinity parallel dialer. Use it to manage contact lists and notes, run the Sequencer, read call logs and AI call scores, pull team and SDR analytics, and enrich phone numbers and email addresses. Webhook subscriptions are managed in the Salesfinity dashboard rather than through this API. ## Base URL All requests go to `https://client-api.salesfinity.co`. There is no separate sandbox host; see the developer portal for the recommended way to test safely. ## Authentication Every operation requires an API key sent in the `x-api-key` request header. Generate a key in the Salesfinity dashboard under **Settings → Connections → API & Webhooks**. A key is scoped to a single team, and every response is filtered to that team. ```bash curl https://client-api.salesfinity.co/v1/team \ --header 'x-api-key: YOUR_API_KEY' ``` ## Errors Every error the API returns is JSON with the same four fields, so a client can parse a failure the same way on every endpoint: ```json { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403, "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10" } ``` `statusCode` matches the HTTP status. `error` is the stable reason phrase to branch on. `message` is human readable, and is an array of strings when request validation fails. `request_id` identifies the request in Salesfinity's logs; include it when you contact support. Note that a missing or invalid API key returns **403**, not 401. ## Request IDs Every response carries an `X-Request-Id` header, and an error body repeats it as `request_id`. To trace a request end to end, send your own `X-Request-Id`: 1 to 128 characters of letters, digits, `.`, `_`, `:` and `-`. Otherwise Salesfinity generates one. ## Request bodies Bodies are JSON. A field the operation does not define is rejected with **400** (`property should not exist`). A body may be up to 10 MB on `/v1/contact-lists` and `/v2/sequencer`, and up to 1 MB everywhere else; a larger one gets **413**. Writes that record a person take a `user_id`: the team member the call acts as. On contact lists and notes, a `user_id` that is not on the team gets **400**. On the Sequencer it must be an active member, or the call gets **403**. ## Pagination List endpoints accept `page` (1-based) and `limit` query parameters. Defaults, maximums and the response envelope differ by endpoint family, so read the `limit` parameter and the response schema on the operation itself. Scored calls and every paged `/v2/sequencer` list return `{ data, pagination: { total, page, limit, pages } }`. Call logs return that shape when a `filters[...]` parameter is sent, and `{ data, pagination: { total, page, next } }` otherwise. ## Rate limits Limits are per team: every API key on a team shares them. Requests are counted per bucket in fixed one-minute windows that start on the minute. | Bucket | Routes | Requests per minute | |---|---|---| | Sequencer reads | `GET /v2/sequencer/*` | 600 | | Sequencer writes | `POST`, `PATCH`, `PUT` and `DELETE` on `/v2/sequencer/*` | 300 | | Heavy reads | `GET /v1/call-log` and `GET /v1/scored-calls` (the lists), `/v1/analytics/*`, `/v1/sequences` and `/v1/sequences/{id}` | 120 | | Everything else | All other endpoints | 1200 | Every response to an authenticated request carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds until the window resets). Over the limit the API returns **429** with a `Retry-After` header giving the seconds to wait. These are the current limits; Salesfinity gives notice before lowering them. ## Idempotency `POST` endpoints outside the Sequencer are not idempotent: cap retries, and confirm state with a `GET` before retrying a create. Every `POST /v2/sequencer/*` endpoint except the three `/preview` endpoints accepts an `Idempotency-Key` header. Keys are kept for 24 hours per team. A retry with the same key and the same request replays the original successful response. The same key with a different body or path returns **409**, and so does a retry while the first request is still running, which is safe to repeat after a moment. A request that fails frees its key, so a retry after a 5xx runs the write again: confirm state with a `GET` before retrying a create that failed with a 5xx. version: 1.0.0 termsOfService: https://salesfinity.ai/terms contact: name: Salesfinity Support email: hello@salesfinity.co url: https://support.salesfinity.ai license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://client-api.salesfinity.co description: Production. The only public Salesfinity API host. security: - ApiKeyAuth: [] tags: - name: Contact Lists description: >- Create, read, merge, and delete CSV contact lists, add or remove the contacts inside them, and put a list's contacts in its dialing queue. - name: Teams description: >- Read the team that owns the API key, including its members, licenses, and statuses. - name: Dispositions description: Read the default and custom call outcomes configured for the team. - name: Sequences description: >- Read the external CRM sequences that appear on the team's call logs, with call counts and first and last use. Not the Salesfinity Sequencer, which is the Sequencer Sequences group. - name: Call Logs description: >- Read the raw call history for the team, with filtering, sorting, and pagination. - name: Analytics description: Aggregated call metrics for the team, by contact list, and by SDR. - name: Snoozed Contacts description: Read and manage contacts that have been snoozed out of the dialing queue. - name: Follow-up Tasks description: Read follow-up tasks created from call outcomes. - name: Custom Fields description: Read the custom field mappings configured for the team. - name: Scored Calls description: Read AI-scored calls with per-facet scoring and coaching recommendations. - name: Notes description: >- Attach freeform notes to a person or company, list them, and pin the ones that matter. - name: Enrichment description: >- Look up phone numbers and work or personal email addresses for a LinkedIn profile, and check the team's remaining enrichment credits. - name: Sequencer Sequences description: >- Create, configure, enable and duplicate Sequencer cadences, and read their analytics. Distinct from the Sequences group, which lists sequence names observed on call logs from an external CRM. - name: Sequencer Steps description: The ordered steps that make up a cadence. - name: Sequencer Templates description: Reusable email subjects and bodies that email steps send from. - name: Sequencer Enrollments description: >- Contacts inside a sequence: where they are in the cadence, and the verbs that move them. Bulk verbs take up to 500 enrollments. - name: Sequencer Enrolment Runs description: >- Background enrollment of up to 5,000 contacts at a time, and the preview that shows what a batch would do. - name: Sequencer Tasks description: The rep task queue a cadence produces, plus standalone one-off tasks. - name: Sequencer Suppression description: >- The team do-not-contact list, checked when someone is enrolled and again before every email is sent. - name: Sequencer Policies description: 'Rules of engagement: what may be enrolled, and what happens at each step.' - name: Sequencer Settings description: Team-level sequencer settings and sending mailboxes. Read-only. externalDocs: description: Salesfinity API documentation url: https://docs.salesfinity.ai paths: /v1/custom-fields: get: tags: - Custom Fields summary: List custom field mappings description: >- Returns the team's custom field mappings: one record for each source (a CRM, or `csv` for CSV uploads) whose field mapping was saved in the dashboard's integration settings. Each entry in `fields` (contacts) and `lead_fields` (leads) ties a field in that source (`external_key`, `external_name`) to the name Salesfinity shows for it (`internal_name`). When contacts are imported from a CRM, each mapped field becomes a custom field on the contact whose `label` is the `internal_name`. The `custom_fields` you send to `POST /v1/contact-lists` and `POST /v1/contact-lists/{id}` are free text and are not checked against these mappings. Reuse an `internal_name` as the `label` to give an API-created contact the same field a CRM-imported one has. Not paginated. The array is empty when nothing is mapped. Records for some CRMs also carry `deal_fields`, `account_fields`, `deal_field_mapping` and `account_field_mapping`. operationId: get-custom-fields responses: '200': description: Every custom field mapping record for the team. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: type: array items: $ref: '#/components/schemas/CustomFieldsDTO' example: - _id: 66e0f3a1b2c3d4e5f6a7b8c9 source: hubspot team: 64f1a2b3c4d5e6f7a8b9c0d1 user: 680edc0d1504192884a148e0 fields: - _id: 66e0f3a1b2c3d4e5f6a7b8ca type: enumeration field_type: select internal_name: Account tier external_key: account_tier external_name: Account Tier lead_fields: [] createdAt: '2026-09-14T09:20:11.204Z' updatedAt: '2026-09-30T16:45:02.871Z' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: headers: X-Request-Id: description: >- Identifies the request in Salesfinity's logs, and matches `request_id` in an error body. Echoes the `X-Request-Id` you sent when it is 1 to 128 characters of letters, digits, `.`, `_`, `:` and `-`; otherwise Salesfinity generates one. schema: type: string example: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10 X-RateLimit-Limit: description: >- Requests allowed per minute in the rate-limit bucket this request counted against. Limits are per team: every API key on the team shares them. schema: type: integer example: 300 X-RateLimit-Remaining: description: Requests left in the current one-minute window for this bucket. schema: type: integer minimum: 0 example: 0 X-RateLimit-Reset: description: >- Seconds until the current window ends and the bucket resets. At least 1 and at most 60. schema: type: integer minimum: 0 example: 12 Retry-After: description: >- Seconds to wait before retrying: the time left in the current one-minute window. At least 1 and at most 60. schema: type: integer minimum: 0 example: 12 schemas: CustomFieldsDTO: type: object properties: _id: type: string description: ID of the mapping record. source: type: string enum: - csv - salesforce - salesforce_sandbox - salesloft - outreach - apollo - hubspot - attio - active-campaign - custom - pipe-drive - monday description: >- The integration the mapping belongs to. `csv` holds the mapping used for CSV uploads. team: type: string description: ID of your team. user: type: string description: ID of the member who first saved the mapping. fields: type: array items: $ref: '#/components/schemas/CustomFieldDTO' description: Mappings for contact fields. lead_fields: type: array items: $ref: '#/components/schemas/CustomFieldDTO' description: Mappings for lead fields, for CRMs that have leads. deal_fields: type: array items: $ref: '#/components/schemas/CustomFieldDTO' description: >- Deal fields to show, for CRMs that support them. Absent when not configured. account_fields: type: array items: $ref: '#/components/schemas/CustomFieldDTO' description: >- Account fields to show, for CRMs that support them. Absent when not configured. deal_field_mapping: type: array description: >- Which CRM fields fill Salesfinity's standard deal fields. Absent when not configured. items: type: object properties: internal_id: type: number external_key: description: A field key, or an array of keys. external_name: description: A field name, or an array of names. account_field_mapping: type: array description: >- Which CRM fields fill Salesfinity's standard account fields. Absent when not configured. items: type: object properties: internal_id: type: number external_key: description: A field key, or an array of keys. external_name: description: A field name, or an array of names. createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - _id - source - team CustomFieldDTO: type: object properties: _id: type: string description: ID of the entry. type: type: string description: >- The field's data type in the source, as that source names it, such as HubSpot's `string` or `enumeration`. example: enumeration field_type: type: string description: >- The field's input type in the source, such as HubSpot's `text` or `select`. example: select internal_name: type: string description: >- The name Salesfinity shows. It becomes the `label` of the contact's custom field when contacts are imported. example: Account tier external_key: type: string description: The field's API name in the source. example: account_tier external_name: type: string description: The field's display name in the source. example: Account Tier Error: type: object title: Error description: >- The error envelope returned by every Salesfinity API error response. The shape is identical across all status codes and all endpoints, and `request_id` is present on every error the API returns. required: - message - error - statusCode - request_id properties: message: description: >- Human-readable description of the failure. A string for most errors, and an array of strings when request validation fails, with one entry per field that did not validate. oneOf: - type: string - type: array items: type: string example: Forbidden resource error: type: string description: >- Stable HTTP reason phrase for the status code, such as `Forbidden`. One exception: a 403 from a `/v2/sequencer` write whose `user_id` has no active plan or seat carries `NO_ACTIVE_PLAN` here. Branch on this rather than on `message`. example: Forbidden statusCode: type: integer format: int32 description: >- HTTP status code, repeated in the body so it survives transports that drop it. example: 403 request_id: type: string description: >- Identifies the request in Salesfinity's logs; the same value as the `X-Request-Id` response header. Include it when you contact support. example: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10 errors: type: array items: type: string description: >- Present on a few Sequencer errors, such as a rules-of-engagement policy whose rules fail the catalog check: one entry per problem. Other fields an upstream service sends are passed through unchanged too. example: message: Forbidden resource error: Forbidden statusCode: 403 request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10 responses: Forbidden: description: >- Forbidden. The `x-api-key` header is missing, malformed, revoked, or belongs to another team. Send a valid key in the `x-api-key` header. Salesfinity returns 403 (not 401) for a missing, malformed, revoked, or wrong-team key. On an operation that takes a `user_id`, 403 can also mean that team member may not do this, for example a Sequencer call acting as an inactive member; `message` then says why. A `/v2/sequencer` write whose `user_id` has no active plan or seat gets `error` set to `NO_ACTIVE_PLAN` instead of `Forbidden`; assign the member a seat. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Forbidden resource error: Forbidden statusCode: 403 request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10 TooManyRequests: description: >- Too Many Requests. The team has used its per-minute budget for this rate-limit bucket; the limit is shared by every API key on the team. Wait the number of seconds in the `Retry-After` header (never more than 60), then retry. The request was refused before it ran, so retrying it is safe even for a write. Pace bulk work with the `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. See /api-reference/rate-limits. headers: Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Rate limit of 300 requests per minute exceeded. Retry in 12s. error: Too Many Requests statusCode: 429 request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10 InternalServerError: description: >- Internal Server Error. Something went wrong on the Salesfinity side. Retry with exponential backoff. If it persists, contact hello@salesfinity.co with the `request_id` from the body, the request path and the timestamp. The contact-list, snoozed-contact and note routes do not validate an ID in the path, and the analytics routes do not validate `user_ids`: an ID that is not a 24-character hexadecimal string returns 500 there, and retrying does not help, so check the ID first. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Internal server error error: Internal Server Error statusCode: 500 request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Team-scoped API key generated in the Salesfinity dashboard under Settings → Connections → API & Webhooks. A missing or invalid key returns HTTP 403. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.