/field-mappings

curl -X POST https://api.merge.dev/api/ats/v1/field-mappings \
     -H "X-Account-Token: X-Account-Token" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "target_field_name": "example_target_field_name",
  "target_field_description": "this is a example description of the target field",
  "remote_field_traversal_path": [
    "example_remote_field"
  ],
  "remote_method": "GET",
  "remote_url_path": "/example-url-path",
  "common_model_name": "ExampleCommonModel"
}'

{
  "model": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "is_integration_wide": true,
    "target_field": {
      "name": "example_target_field_name",
      "description": "this is a example description of a target field",
      "is_organization_wide": true
    },
    "remote_field": {
      "remote_key_name": "example_remote_field_key",
      "schema": {
        "type": "string"
      },
      "remote_endpoint_info": {
        "method": "GET",
        "url_path": "/example-url-path",
        "field_traversal_path": [
          "example_remote_field_key"
        ]
      }
    },
    "jmes_path": "[0].example_jmes_path",
    "advanced_mapping_expression": "$[0].example_jsonata"
  },
  "warnings": [
    {
      "title": "Unrecognized Field",
      "detail": "An unrecognized field, age, was passed in with request data.",
      "problem_type": "UNRECOGNIZED_FIELD",
      "source": {
        "pointer": "/age"
      },
      "block_merge_link": true,
      "raw_error": "string",
      "error_code": 1
    }
  ],
  "errors": [
    {
      "title": "Missing Required Field",
      "detail": "custom_fields is a required field on model.",
      "problem_type": "MISSING_REQUIRED_FIELD",
      "source": {
        "pointer": "/model/custom_fields"
      },
      "block_merge_link": true,
      "raw_error": "string",
      "error_code": 1
    }
  ],
  "logs": [
    {
      "log_id": "99433219-8017-4acd-bb3c-ceb23d663832",
      "dashboard_view": "https://app.merge.dev/logs/99433219-8017-4acd-bb3c-ceb23d663832",
      "log_summary": {
        "url": "www.exampleintegration.com/api/v1/exampleapi",
        "method": "POST",
        "status_code": 200
      }
    }
  ]
}

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.

curl -X POST https://api.merge.dev/api/ats/v1/field-mappings \
     -H "X-Account-Token: X-Account-Token" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "target_field_name": "example_target_field_name",
  "target_field_description": "this is a example description of the target field",
  "remote_field_traversal_path": [
    "example_remote_field"
  ],
  "remote_method": "GET",
  "remote_url_path": "/example-url-path",
  "common_model_name": "ExampleCommonModel"
}'

{
  "model": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "is_integration_wide": true,
    "target_field": {
      "name": "example_target_field_name",
      "description": "this is a example description of a target field",
      "is_organization_wide": true
    },
    "remote_field": {
      "remote_key_name": "example_remote_field_key",
      "schema": {
        "type": "string"
      },
      "remote_endpoint_info": {
        "method": "GET",
        "url_path": "/example-url-path",
        "field_traversal_path": [
          "example_remote_field_key"
        ]
      }
    },
    "jmes_path": "[0].example_jmes_path",
    "advanced_mapping_expression": "$[0].example_jsonata"
  },
  "warnings": [
    {
      "title": "Unrecognized Field",
      "detail": "An unrecognized field, age, was passed in with request data.",
      "problem_type": "UNRECOGNIZED_FIELD",
      "source": {
        "pointer": "/age"
      },
      "block_merge_link": true,
      "raw_error": "string",
      "error_code": 1
    }
  ],
  "errors": [
    {
      "title": "Missing Required Field",
      "detail": "custom_fields is a required field on model.",
      "problem_type": "MISSING_REQUIRED_FIELD",
      "source": {
        "pointer": "/model/custom_fields"
      },
      "block_merge_link": true,
      "raw_error": "string",
      "error_code": 1
    }
  ],
  "logs": [
    {
      "log_id": "99433219-8017-4acd-bb3c-ceb23d663832",
      "dashboard_view": "https://app.merge.dev/logs/99433219-8017-4acd-bb3c-ceb23d663832",
      "log_summary": {
        "url": "www.exampleintegration.com/api/v1/exampleapi",
        "method": "POST",
        "status_code": 200
      }
    }
  ]
}

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.

Authentication

AuthorizationBearer

Token-based authentication with required prefix “Bearer”

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.

target_field_namestringRequired>=1 character

The name of the target field you want this remote field to map to.

target_field_descriptionstringRequired>=1 character

The description of the target field you want this remote field to map to.

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.

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

/field-mappings

/field-mappings

Authentication

Headers

Query parameters

Request

Response

Authentication

Headers

Query parameters

Request

Response

$	curl -X POST https://api.merge.dev/api/ats/v1/field-mappings \
>	-H "X-Account-Token: X-Account-Token" \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"target_field_name": "example_target_field_name",
>	"target_field_description": "this is a example description of the target field",
>	"remote_field_traversal_path": [
>	"example_remote_field"
>	],
>	"remote_method": "GET",
>	"remote_url_path": "/example-url-path",
>	"common_model_name": "ExampleCommonModel"
>	}'

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	}