For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Logo
Resources
Log inGet a demo
Get startedAPI referenceImplementation
Get startedAPI referenceImplementation
    • Overview
        • Field Mapping
          • GET/field-mappings
          • POST/field-mappings
          • DEL/field-mappings/{field_mapping_id}
          • PATCH/field-mappings/{field_mapping_id}
          • GET/remote-fields
          • GET/target-fields
          • POST/target-fields

Get started

  • Overview
  • Introduction
  • Unified API
  • Linked Account
  • Merge Link
  • Use cases

Implementation

  • Sandboxes
  • SDKs
  • API access
  • Syncing data
  • Writing data
  • Data minimization
  • Supplemental data
  • Errors
  • Integration metadata

API reference

  • ATS
  • HRIS
  • Accounting
  • Ticketing
  • CRM
  • File Storage
  • Knowledge Base
  • Chat

Resources

  • Help Center
  • Merge.dev
  • Changelog
© Merge 2026Terms of usePrivacy policy
UnifiedAgent HandlerGateway
UnifiedAgent HandlerGateway
Resources
Log inGet a demo
Linked AccountField Mapping

/field-mappings

POST
/ticketing/v1/field-mappings
POST
/api/ticketing/v1/field-mappings
$curl -X POST https://api.merge.dev/api/ticketing/v1/field-mappings \
>     -H "X-Account-Token: X-Account-Token" \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "remote_field_traversal_path": [
>    "example_remote_field"
>  ],
>  "remote_method": "GET",
>  "remote_url_path": "/example-url-path",
>  "common_model_name": "ExampleCommonModel"
>}'
201Created
1{
2  "model": {
3    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4    "is_integration_wide": true,
5    "target_field": {
6      "name": "example_target_field_name",
7      "description": "this is a example description of a target field",
8      "is_organization_wide": true
9    },
10    "remote_field": {
11      "remote_key_name": "example_remote_field_key",
12      "schema": {
13        "type": "string"
14      },
15      "remote_endpoint_info": {
16        "method": "GET",
17        "url_path": "/example-url-path",
18        "field_traversal_path": [
19          "example_remote_field_key"
20        ]
21      }
22    },
23    "jmes_path": "[0].example_jmes_path",
24    "advanced_mapping_expression": "$[0].example_jsonata"
25  },
26  "warnings": [
27    {
28      "title": "Unrecognized Field",
29      "detail": "An unrecognized field, age, was passed in with request data.",
30      "problem_type": "UNRECOGNIZED_FIELD",
31      "source": {
32        "pointer": "/age"
33      },
34      "block_merge_link": true,
35      "raw_error": "string",
36      "error_code": 1
37    }
38  ],
39  "errors": [
40    {
41      "title": "Missing Required Field",
42      "detail": "custom_fields is a required field on model.",
43      "problem_type": "MISSING_REQUIRED_FIELD",
44      "source": {
45        "pointer": "/model/custom_fields"
46      },
47      "block_merge_link": true,
48      "raw_error": "string",
49      "error_code": 1
50    }
51  ],
52  "logs": [
53    {
54      "log_id": "99433219-8017-4acd-bb3c-ceb23d663832",
55      "dashboard_view": "https://app.merge.dev/logs/99433219-8017-4acd-bb3c-ceb23d663832",
56      "log_summary": {
57        "url": "www.exampleintegration.com/api/v1/exampleapi",
58        "method": "POST",
59        "status_code": 200
60      }
61    }
62  ]
63}

Create new Field Mappings that will be available after the next scheduled sync. This will cause the next sync for this Linked Account to sync ALL data from start.

Was this page helpful?
Previous

/field-mappings

Next

/field-mappings/{field_mapping_id}

Authentication

AuthorizationBearer

Token-based authentication with required prefix “Bearer”

Headers

X-Account-TokenstringRequired
Token identifying the end user.

Query parameters

exclude_remote_field_metadatabooleanOptional

If true, remote fields metadata is excluded from each field mapping instance (i.e. remote_fields.remote_key_name and remote_fields.schema will be null). This will increase the speed of the request since these fields require some calculations.

remote_data_iteration_countintegerOptional
Number of common model instances to iterate through when fetching remote data for field mappings. Defaults to 250 if not provided.

Request

This endpoint expects an object.
remote_field_traversal_pathlist of anyRequired

The field traversal path of the remote field listed when you hit the GET /remote-fields endpoint.

remote_methodstringRequired>=1 character
The method of the remote endpoint where the remote field is coming from.
remote_url_pathstringRequired>=1 character
The path of the remote endpoint where the remote field is coming from.
common_model_namestringRequired>=1 character
The name of the Common Model that the remote field corresponds to in a given category.
target_field_namestringOptional>=1 character

The name of the target field you want this remote field to map to. Required if organization_wide_target_field is not provided.

target_field_descriptionstringOptional>=1 character

The description of the target field you want this remote field to map to. Required if organization_wide_target_field is not provided.

organization_wide_target_fieldstringOptional>=1 character

The name or key of an existing Organization-wide target field to map to. When provided, target_field_name and target_field_description are optional.

is_integration_widebooleanOptionalDefaults to false

If true, creates an integration-wide field mapping that applies to all Linked Accounts for the integration. Requires organization_wide_target_field.

jmes_pathstringOptional>=1 character

DEPRECATED: Use ‘advanced_mapping_expression’ instead.

advanced_mapping_expressionstringOptional>=1 character
A JSONata expression used to transform the remote field data.

Response

modelobject
warningslist of objects
errorslist of objects
logslist of objects