Call a connector method

Once you’ve identified the Connector Method you wish to call, and the authenticated Account Connector you wish to call it against, you then have a choice how to pass any necessary values to Cyclr to execute that Method:

Cyclr API Endpoints

POST /v1.0/account/connectors/{id}/methods/{methodId}
Values can be passed using numeric property names that represent the Parameters, Fields and Mergefields used by the Method.
POST /v1.0/account/connectors/{id}/methods/{methodId}/body
Values can be passed using a string representation of the JSON/XML you wish to send.

The Cyclr API has a GET version of the POST /v1.0/account/connectors/{id}/methods/{methodId} endpoint which exists for legacy reasons. As the GET version doesn't allow a Request Body to be provided, we would recommend using the POST version instead.

POST /v1.0/account/connectors/{id}/methods/{methodId}

This endpoint accepts a Request Body for Parameters, Fields and Mergefields that uses their numeric Ids as property names.

Example Request with Parameters

If the Connector Method being used requires any values to be passed, you can include them in the Request Body to the Cyclr API endpoint:

CODE

POST https://{CyclrAPIDomain}/v1.0/account/connectors/{AccountConnectorID}/methods/{methodId}
Authorization: Bearer {AccessToken}
Content-Type: application/json
X-Cyclr-Account: {AccountAPIID}

{
    "Parameters": {
        "400123": "true"
    },
	"Fields": {
		"24718359": "Mr",
		"24718360": "John",
		"24718361": "Smith",
		"24718362": "johnsmith@example.com"
	}
}

Request Explanation

Parameter	Description
`{CyclrAPIDomain}`	Replace with the appropriate API domain for your Partner Console.
`{AccountConnectorID}`	Replace with an account connector ID. See Get account connectors.
`{methodId}`	Indicates the Method to call. Either: the numeric Method Id, or the MethodUniqueIdentifier. See Get connector methods.
`{AccessToken}`	A Cyclr API access token.
`{AccountAPIID}`	The API ID of the account to work in.
`Parameters`	An object where keys and values can be added to pass values for Parameters, e.g.: JSON `"Parameters": { "400123": "true", "400125": "asc" }`
`Fields`	An object where keys and values can be added to pass values for Request Fields, e.g.: JSON `"Fields": { "194009": "John", "194010": "Smith" }`
`Mergefields`	An object where keys and values can be added to pass values for Mergefields, e.g.: JSON `"Mergefields": { "305491": "customers", "305494": "100" }`

See MethodUniqueIdentifier or Method Id? for an explanation of why you might choose one over the other.

Example Request without Parameters

Some Connector Methods don’t expose any values to pass in so they can be called with an empty Request Body:

CODE

POST https://{CyclrAPIDomain}/v1.0/account/connectors/{AccountConnectorID}/methods/{methodId}
Authorization: Bearer {AccessToken}
Content-Type: application/json
X-Cyclr-Account: {AccountAPIID}

{}

POST /v1.0/account/connectors/{id}/methods/{methodId}/body

This endpoint enables you to make requests without using Id values for the Parameters, Fields and Mergefields objects. Instead, you use string values of their properties.

If you’re working with a MethodUniqueIdentifier to always use the latest Release of a Connector, this endpoint is helpful as you don’t need to ensure you have the latest Id values of the Parameters, etc.

It is still possible that a Method’s definition will change, but typically those changes wouldn’t remove existing properties you are working with.

This endpoint also accepts a string representing the JSON or XML Request Body, using Cyclr’s Target Name properties, rather than their Id values. That is provided in the RequestBody property.

Request Body Definition

JSON

{
	"RequestBody": "string",
	"Parameters": {},
	"Mergefields": {},
	"CustomCategoryId": 0
}

Example Request

JSON

POST https://{CyclrAPIDomain}/v1.0/account/connectors/{AccountConnectorID}/methods/{methodId}/body
Authorization: Bearer {AccessToken}
Content-Type: application/json
X-Cyclr-Account: {AccountAPIID}

{
	"RequestBody": "{\"Salutation\":\"Mr\",\"FirstName\":\"John\",\"LastName\":\"Smith\",\"Email\":\"johnsmith@example.com\"}",
	"Parameters": {
		"Exclude": "false"
	},
	"Mergefields": {
		"ObjectType": "contact"
	}
}

Request Explanation

Parameter	Description
`{CyclrAPIDomain}`	Replace with the appropriate API domain for your Partner Console.
`{AccountConnectorID}`	Replace with an account connector ID. See Get account connectors.
`{methodId}`	Indicates the Method to call. Either: the numeric Method Id, or the MethodUniqueIdentifier. See Get connector methods.
`{AccessToken}`	A Cyclr API access token.
`{AccountAPIID}`	The API ID of the account to work in.

`RequestBody`	A value to pass to Cyclr containing values for the Connector Method’s Request Fields. Provided as an escaped string of JSON or XML, e.g.: JSON `"RequestBody": "{\"FirstName\":\"John\",\"LastName\":\"Smith\",\"Email\":\"johnsmith@example.com\"}"` The structure of the string is explained here.
`Parameters`	An object where keys and values can be added to pass values for Parameters, e.g.: JSON `"Parameters": { "Exclude": "false", "Order": "asc" }` The names of these properties are the `TargetName` values of their `Parameters`. More on that here.
`Mergefields`	An object where keys and values can be added to pass values for Mergefields, e.g.: JSON `"Mergefields": { "ObjectType": "contact", "Version": "10.00" }` The names of these properties are the `TargetName` values of their `Parameters`. More on that here.

Identifying the Property Names to use

To obtain the correct names of properties to pass to this endpoint, you can use a mixture of the Cyclr interface and the Cyclr API:

Cyclr Interface

Navigate to the Account Connector setup page and select a Method, then view its Request Fields. You can use the “Field Location” column to determine the properties available for use in the RequestBody property.

You can also view an example request object by clicking the </> button to use as a starting point for the RequestBody property's value, ensuring you escape it before using in a call to Cyclr’s API.

Cyclr API

Using the GET /v1.0/connectors/{...}/methods endpoints, their Response for each Method includes:

a Parameters property - each item it contains has a TargetName property.
This contains entries for both QueryString and Mergefield values.
a RequestFields property - each item it contains has a Location property.
This contains entries for the Request Fields Cyclr accepts.

We use standard JavaScript “dot notation” so a Location of "Parent.Child" would correspond to the following property in JSON:

CODE

{
	"Parent": {
		"Child": "Value"
	}
}

Example Response

Depending on what the Connector Method you call does, you’ll get a suitable Response back after Cyclr has executed the call and received a Response from the third-party API.

The Response may be in JSON or XML, depending on the third-party API’s setup.

If the Connector Method you are calling retrieves data, such as a “List All Contacts” Method, Cyclr may need to make multiple requests to the third-party’s API to retrieve all the data using pagination.

In those situations, you will only receive a Response once Cyclr has retrieved all of the data.

The example below shows what might come back if you were to call a “List All Contacts” Connector Method that returns JSON data:

JSON

{
    "records": [
        {
            "Id": "1001",
            "FirstName": "John",
            "LastName": "Doe",
            "Name": "John Doe",
            "Email": "johndoe@example.com"
        },
        {
            "Id": "1002",
            "FirstName": "Jane",
            "LastName": "Doe",
            "Name": "Jane Doe",
            "Email": "janedoe@example.com"
        }
    ]
}

Some Cyclr Connector Methods alter the format of the Response returned by the third-party API to improve how it can be used within Cyclr. As a result, if you’re familiar with the third-party’s API endpoints, you may not see the Response come back as you expect.

400 Error Response

If you receive a 400 Error Response from Cyclr’s API when calling one of the endpoints above, details of the issue should be found in the Response Body.

The most common errors that occur relate to missing required fields, details of which should be included in the Response Body.

Example Response

CODE

{
  "Message": "Required parameter Mobile Phone was not provided",
  "ParameterId": 1726820,
  "TargetName": "MobilePhone"
}

Using the information returned, you should be able to add the missing property, whether you’re using an endpoint that expects Id values or TargetNames and Locations.

403 Error Response

If you receive a 403 Error Response when calling a Connector Method, it is likely that your IP address hasn’t been added to Cyclr’s Allow List.

See this article for more information.