NAV
cURL

Introduction

Base URL:

https://api.terminusapp.com/

Terminus's RESTful API allows you to perform various operations on your Terminus account.

All responses (including errors) are returned with standard HTTP response codes and JSON-formatted data.

Authentication

Authenticated Request :

curl "https://api.terminusapp.com/v1/projects" \
  -u YOUR_API_KEY:
# The colon prevents curl from asking for a password.

The Terminus API uses API keys to authenticate requests. You can create and manage your API keys in your Terminus account.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth, use -H "Authorization: Bearer YOUR_API_KEY" instead of -u YOUR_API_KEY.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Object IDs

Object data responses will include JSON keys such as id, project_id and others. Before storing or using these IDs, consider the following:

Campaigns

List Campaign Values

Get UTM Campaign values

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_6xF8C4dLtN/campaigns" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/campaigns

Parameters

Name Description
project_id required Project ID starting with prj_
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "value": "blog-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "blog-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
value Campaign tag
fields_map Fields Data saved for the this Campaign Value
parameter_format_id Parameter Format ID used to save the Campaign Value

Contents

List Content Values

Get UTM Content values

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_fQoI9KzLRz/contents" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/contents

Parameters

Name Description
project_id required Project ID starting with prj_
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "value": "blog-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "blog-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
value Content tag
fields_map Fields Data saved for the this Content Value
parameter_format_id Parameter Format ID used to save the Content Value

Conventions

List conventions

Get a list of conventions. This returns minimal information for each convention.

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_fSLC0OxFko/conventions" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/conventions

Parameters

Name Description
project_id required Project ID starting with prj_
items Number of items to be returned. This can range between 1 and 100. Default is 10.
page Specify the page number to get items that cannot be returned in a single request. Default is 1.

Response

{
  "data": [
    {
      "id": 89,
      "name": "Main Convention"
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
data An array of items
meta[page] Current page number
meta[has_more] true if more items are available on the next page. Otherwise false

Get a convention

Get detailed information about a particular convention

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_xlZL9Y5II4/conventions/90" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/conventions/:convention_id

Parameters

Name Description
project_id required Project ID starting with prj_
convention_id required Convention id

Response

{
  "id": 90,
  "name": "Main Convention",
  "description": null,
  "shared": false,
  "field_mode": false,
  "campaign_format_id": 589,
  "medium_format_id": 590,
  "source_format_id": 591,
  "content_format_id": 592,
  "term_format_id": 593,
  "disable_campaign": false,
  "disable_medium": false,
  "disable_source": false,
  "disable_content": false,
  "disable_term": false,
  "custom_formats": [
    {
      "custom_parameter_id": 832,
      "parameter_format_id": 594,
      "disable": false
    }
  ],
  "info_field_formats": [
    {
      "info_field_id": 716,
      "parameter_format_id": 595,
      "disable": false
    }
  ],
  "fields": [
    {
      "id": 1079,
      "name": "Interval",
      "description": null,
      "required": true,
      "type": "OptionField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": ":int",
      "option_values": [
        {
          "name": "weekly",
          "description": "Weekly newsletter",
          "position": 1
        },
        {
          "name": "monthly",
          "description": "Monthly newsletter",
          "position": 2
        },
        {
          "name": "yearly",
          "description": "",
          "position": 3
        }
      ]
    },
    {
      "id": 1080,
      "name": "Campaign Date",
      "description": null,
      "required": true,
      "type": "DateField",
      "date_format": "YYYY_MM_DD",
      "constant_value": null,
      "prefix": "date_",
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 1081,
      "name": "Headline",
      "description": null,
      "required": true,
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 1082,
      "name": "Headline",
      "description": null,
      "required": true,
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 1083,
      "name": "Email",
      "description": null,
      "required": true,
      "type": "ConstantField",
      "date_format": null,
      "constant_value": "email",
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 1084,
      "name": "Email Source",
      "description": null,
      "required": true,
      "type": "OptionField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [
        {
          "name": "newsletter1",
          "description": null,
          "position": 1
        },
        {
          "name": "newsletter2",
          "description": null,
          "position": 2
        }
      ]
    },
    {
      "id": 1085,
      "name": "Email Content",
      "description": null,
      "required": true,
      "type": "OptionField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [
        {
          "name": "content1",
          "description": null,
          "position": 1
        },
        {
          "name": "content2",
          "description": null,
          "position": 2
        }
      ]
    },
    {
      "id": 1086,
      "name": "Email Term",
      "description": null,
      "required": true,
      "type": "OptionField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [
        {
          "name": "term1",
          "description": null,
          "position": 1
        },
        {
          "name": "term2",
          "description": null,
          "position": 2
        }
      ]
    },
    {
      "id": 1087,
      "name": "Product",
      "description": null,
      "required": true,
      "type": "OptionField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": ":int",
      "option_values": [
        {
          "name": "shoes",
          "description": null,
          "position": 1
        },
        {
          "name": "shirts",
          "description": null,
          "position": 2
        },
        {
          "name": "socks",
          "description": null,
          "position": 3
        }
      ]
    },
    {
      "id": 1088,
      "name": "Custom Date",
      "description": null,
      "required": true,
      "type": "DateField",
      "date_format": "YYYY_MM_DD",
      "constant_value": null,
      "prefix": "date_",
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 1089,
      "name": "Name",
      "description": null,
      "required": true,
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 1090,
      "name": "Headline",
      "description": null,
      "required": true,
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": ":h",
      "option_values": [

      ]
    },
    {
      "id": 1091,
      "name": "Headline",
      "description": null,
      "required": true,
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": ":h",
      "option_values": [

      ]
    },
    {
      "id": 1092,
      "name": "Goal",
      "description": null,
      "required": true,
      "type": "OptionField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [
        {
          "name": "visit",
          "description": "Website visit",
          "position": 1
        },
        {
          "name": "sale",
          "description": "Sale",
          "position": 2
        },
        {
          "name": "lead",
          "description": "",
          "position": 3
        }
      ]
    },
    {
      "id": 1093,
      "name": "Purpose",
      "description": null,
      "required": true,
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    }
  ]
}
Name Description
id Convention id
name Given name of the convention
description Given description of the convention
shared true if shared with other projects
field_mode true if Field Mode is enabled
campaign_format_id Parameter Format ID for UTM Campaign
medium_format_id Parameter Format ID for UTM Medium
source_format_id Parameter Format ID for UTM Source
content_format_id Parameter Format ID for UTM Content
term_format_id Parameter Format ID for UTM Term
disable_campaign true if UTM Campaign is disabled
disable_medium true if UTM Medium is disabled
disable_source true if UTM Source is disabled
disable_content true if UTM Content is disabled
disable_term true if UTM Term is disabled
custom_formats[custom_parameter_id] Custom Parameter ID for the Format
custom_formats[parameter_format_id] Parameter Format ID for the custom parameter
custom_formats[disable] true if this custom parameter is disabled
info_field_format[info_field_id] Info Field ID for the Format
info_field_format[parameter_format_id] Parameter Format ID for the info field
info_field_format[disable] true if this info field is disabled
fields All fields in the convention

Custom Parameter Values

List Custom Parameter Values

Get a list of Custom Parameter Values for a specific Custom Parameter

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_O8IxJmQCWv/custom_parameter_values?custom_parameter_id=833" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/custom_parameter_values

Parameters

custom_parameter_id: 833
Name Description
project_id required Project ID starting with prj_
custom_parameter_id required Custom Parameter ID
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "value": "Festive10",
      "active": false,
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "Festive20",
      "active": true,
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "Festive30",
      "active": false,
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "Festive40",
      "active": true,
      "fields_map": [

      ],
      "parameter_format_id": null
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
value Custom Parameter Value
active Whether the Custom Parameter Value is active
fields_map Fields Data saved for the this Custom Parameter Value
parameter_format_id Parameter Format ID used to save the Custom Parameter Value
custom_parameter[name] Name of the Custom Parameter

Custom Parameters

List Custom Parameters

Get a list of Custom Parameters

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_m2esBYt7Im/custom_parameters" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/custom_parameters

Parameters

Name Description
project_id required Project ID starting with prj_
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "id": 835,
      "name": "coupon",
      "active": true,
      "description": null,
      "required": false,
      "expression": "",
      "generated": false
    },
    {
      "id": 836,
      "name": "test parameter",
      "active": true,
      "description": null,
      "required": false,
      "expression": "",
      "generated": false
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
id Custom Parameter ID
name Custom Parameter Name
active Whether the Custom Parameter field is active
description Custom Parameter Description
required Whether the Custom Parameter is Required
expression Expression to generate the Custom Parameter
generated Whether the Custom Parameter is generated based on the expression set

Info Field Values

List Info Field Values

Get a list of Info Field Values for a specific Info Field

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_VCDnOq5tis/info_field_values?info_field_id=717" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/info_field_values

Parameters

info_field_id: 717
Name Description
project_id required Project ID starting with prj_
info_field_id required Info Field ID
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "value": "Jared",
      "active": false,
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "Richard",
      "active": true,
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "Monica",
      "active": false,
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "Carol",
      "active": true,
      "fields_map": [

      ],
      "parameter_format_id": null
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
name Info Field Value
active Whether the Info Field Value is active
fields_map Fields Data saved for the this Info Field Value
parameter_format_id Parameter Format ID used to save the Info Field Value
info_field[name] Name of the Info Field

Info Fields

List Info Fields

Get a list of Info Fields

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_uLuJL12DLh/info_fields" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/info_fields

Parameters

Name Description
project_id required Project ID starting with prj_
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "id": 719,
      "name": "Info Field 1",
      "description": null,
      "expression": "",
      "required": false,
      "generated": false
    },
    {
      "id": 720,
      "name": "Info Field 2",
      "description": null,
      "expression": "",
      "required": false,
      "generated": false
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
id Info Field ID
name Info Field Name
description Info Field Description
expression Expression to generate the Info Field
required Whether the Info Field is Required
generated Whether the Info Field is generated based on the expression set

Links

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_0uWAHmB1Fo/links" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/links

Parameters

Name Description
project_id required Project ID starting with prj_
created_at[gt] Return items created after a certain date. The value should be an integer Unix timestamp.
updated_at[gt] Return items updated after a certain date. The value should be an integer Unix timestamp.
items Number of items to be returned. This can range between 1 and 100. Default is 10.
page Specify the page number to get items that cannot be returned in a single request. Default is 1.

Response

{
  "data": [
    {
      "id": 3882,
      "url": "https://www.example.com/",
      "long_url": "https://www.example.com/?coupon=50p_off&cid=monthly-date_20200911-head_nowwork-ads&utm_source=linkedin&utm_medium=social&utm_campaign=monthly-date_20200911-head_nowwork-ads",
      "description": "Blog links",
      "campaign": {
        "value": "monthly-date_20200911-head_nowwork-ads",
        "fields_map": [
          {
            "prefix": null,
            "suffix": null,
            "field_id": 467,
            "field_name": "Interval",
            "final_value": "monthly",
            "input_value": "monthly"
          },
          {
            "prefix": "date_",
            "suffix": "",
            "field_id": 477,
            "field_name": "Date",
            "final_value": "date_20200911",
            "input_value": "20200911"
          },
          {
            "prefix": "head_",
            "suffix": "",
            "field_id": 479,
            "field_name": "Name",
            "final_value": "head_nowwork",
            "input_value": "nowwork"
          },
          {
            "prefix": null,
            "suffix": null,
            "field_id": 478,
            "field_name": "Channel",
            "final_value": "ads",
            "input_value": "ads"
          }
        ],
        "parameter_format_id": 12345
      },
      "medium": {
        "value": "social",
        "fields_map": [

        ],
        "parameter_format_id": null
      },
      "source": {
        "value": "linkedin",
        "fields_map": [

        ],
        "parameter_format_id": null
      },
      "content": null,
      "term": null,
      "custom_parameter_values": [
        {
          "value": "50p_off",
          "active": true,
          "fields_map": [

          ],
          "parameter_format_id": null,
          "custom_parameter": {
            "name": "coupon"
          }
        },
        {
          "value": "monthly-date_20200911-head_nowwork-ads",
          "active": true,
          "fields_map": [
            {
              "prefix": null,
              "suffix": null,
              "field_id": 467,
              "field_name": "Interval",
              "final_value": "monthly",
              "input_value": "monthly"
            },
            {
              "prefix": "date_",
              "suffix": "",
              "field_id": 477,
              "field_name": "Date",
              "final_value": "date_20200911",
              "input_value": "20200911"
            },
            {
              "prefix": "head_",
              "suffix": "",
              "field_id": 479,
              "field_name": "Name",
              "final_value": "head_nowwork",
              "input_value": "nowwork"
            },
            {
              "prefix": null,
              "suffix": null,
              "field_id": 478,
              "field_name": "Channel",
              "final_value": "ads",
              "input_value": "ads"
            }
          ],
          "parameter_format_id": 56789,
          "custom_parameter": {
            "name": "cid"
          }
        }
      ],
      "info_field_values": [
        {
          "value": "Bob Smith",
          "active": true,
          "fields_map": [

          ],
          "parameter_format_id": null,
          "info_field": {
            "name": "Requester"
          }
        },
        {
          "value": "Buy Now",
          "active": true,
          "fields_map": [

          ],
          "parameter_format_id": null,
          "info_field": {
            "name": "Ad Headline"
          }
        }
      ],
      "labels": [
        {
          "name": "urgent"
        },
        {
          "name": "blog"
        }
      ],
      "short_url": {
        "clicks": 0,
        "url": "https://shor.ty/0kuszj"
      },
      "created_at": 1605052800,
      "updated_at": 1712255750,
      "created_by": {
        "email": "abc@example.com"
      },
      "created_by_api": false
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
data An array of items
meta[page] Current page number
meta[has_more] true if more items are available on the next page. Otherwise false

A link can be created with or without a convention. When creating a link with a convention, pass the values for the fields in the convention. The fields data can be obtained from Convention endpoints.

Request Endpoint

curl "https://api.terminusapp.com/v1/projects/prj_8TnbZIDReq/links" -d '{"url":"http://www.website-1.com/","convention":{"id":91,"input_fields":[{"field_id":1094,"input_value":"weekly"},{"field_id":1095,"input_value":"2024-12-20"},{"field_id":1096,"input_value":"testing123"},{"field_id":1097,"input_value":"email"},{"field_id":1098,"input_value":"newsletter1"}]},"utm":{"content":{"tag":"content-test"},"term":{"tag":"term-test"}},"custom":{"coupon":{"tag":"custom1-test"}},"info":{"Requester":{"tag":"info1-test"}},"label_names":["test-label1"],"description":"Test Description for Link","short_url_key":"custom_url_key","skip_url_validation":false}' -X POST \
    -H "Content-Type: application/json" \
    -u YOUR_API_KEY:

POST /v1/projects/:project_id/links

Parameters

{"url":"http://www.website-1.com/","convention":{"id":91,"input_fields":[{"field_id":1094,"input_value":"weekly"},{"field_id":1095,"input_value":"2024-12-20"},{"field_id":1096,"input_value":"testing123"},{"field_id":1097,"input_value":"email"},{"field_id":1098,"input_value":"newsletter1"}]},"utm":{"content":{"tag":"content-test"},"term":{"tag":"term-test"}},"custom":{"coupon":{"tag":"custom1-test"}},"info":{"Requester":{"tag":"info1-test"}},"label_names":["test-label1"],"description":"Test Description for Link","short_url_key":"custom_url_key","skip_url_validation":false}
Name Description
project_id required Project ID starting with prj_
url required Destination URL
convention[id] Convention ID. REQUIRED only while creating a link with convention
convention[input_fields][field_id] Field id. REQUIRED only while creating a link with convention
convention[input_fields][input_value] Input Value for Field. REQUIRED only while creating the link with convention
utm[campaign][tag] Value for UTM Campaign tag. REQUIRED if configured in the project and not set via a convention
utm[medium][tag] Value for UTM Medium tag. REQUIRED if configured in the project and not set via a convention.
utm[source][tag] Value for UTM Source tag. REQUIRED if configured in the project and not set via a convention.
utm[content][tag] Value for UTM Content tag. REQUIRED if configured in the project and not set via a convention.
utm[term][tag] Value for UTM Term tag. REQUIRED if configured in the project and not set via a convention.
custom[parameter_name][tag] Value for Custom Parameter tag. Replace the parameter_name with the actual custom parameter name. REQUIRED if configured in the project and not set via a convention.
info[info_field_name][tag] Value for Info Field. Replace the info_field_name with the actual info field name. REQUIRED if configured in the project and not set via a convention.
label_names Array of labels as strings, e.g. ["blog", "urgent"]
description Description for Link
skip_monitoring Skip URL monitoring on this URL
short_url_key Short URL key to use for this URL. If not specified, it will be automatically generated
skip_url_validation Skip URL validation on this URL

Response

{
  "id": 3884,
  "url": "http://www.website-1.com/",
  "long_url": "http://www.website-1.com/?coupon=custom1-test&utm_source=newsletter1&utm_medium=email&utm_campaign=weekly:int-date_2024_12_20-testing123&utm_term=term-test&utm_content=content-test",
  "description": "Test Description for Link",
  "campaign": {
    "value": "weekly:int-date_2024_12_20-testing123",
    "fields_map": [
      {
        "field_id": 1094,
        "field_name": "Interval",
        "final_value": "weekly:int",
        "input_value": "weekly",
        "prefix": null,
        "suffix": ":int"
      },
      {
        "field_id": 1095,
        "field_name": "Campaign Date",
        "final_value": "date_2024_12_20",
        "input_value": "2024_12_20",
        "prefix": "date_",
        "suffix": null
      },
      {
        "field_id": 1096,
        "field_name": "Headline",
        "final_value": "testing123",
        "input_value": "testing123",
        "prefix": null,
        "suffix": null
      }
    ],
    "parameter_format_id": 596
  },
  "medium": {
    "value": "email",
    "fields_map": [
      {
        "field_id": 1097,
        "field_name": "Email",
        "final_value": "email",
        "input_value": "email",
        "prefix": null,
        "suffix": null
      }
    ],
    "parameter_format_id": 597
  },
  "source": {
    "value": "newsletter1",
    "fields_map": [
      {
        "field_id": 1098,
        "field_name": "Email Source",
        "final_value": "newsletter1",
        "input_value": "newsletter1",
        "prefix": null,
        "suffix": null
      }
    ],
    "parameter_format_id": 598
  },
  "content": {
    "value": "content-test",
    "fields_map": [

    ],
    "parameter_format_id": null
  },
  "term": {
    "value": "term-test",
    "fields_map": [

    ],
    "parameter_format_id": null
  },
  "custom_parameter_values": [
    {
      "value": "custom1-test",
      "active": true,
      "fields_map": [

      ],
      "parameter_format_id": null,
      "custom_parameter": {
        "name": "coupon"
      }
    }
  ],
  "info_field_values": [
    {
      "value": "info1-test",
      "active": true,
      "fields_map": [

      ],
      "parameter_format_id": null,
      "info_field": {
        "name": "Requester"
      }
    }
  ],
  "labels": [
    {
      "name": "test-label1"
    }
  ],
  "short_url": {
    "clicks": 0,
    "url": "https://shor.ty/custom_url_key"
  },
  "created_at": 1734672973,
  "updated_at": 1734672973,
  "created_by": null,
  "created_by_api": true,
  "duplicate": false
}
Name Description
id Link Id
url Link base URL
long_url Link long URL with all the parameters
description Description for Link
campaign UTM campaign with final value, fields_map array and parameter_format_id
medium UTM medium with final value, fields_map array and parameter_format_id
source UTM source with final value, fields_map array and parameter_format_id
content UTM content with final value, fields_map array and parameter_format_id
term UTM term with final value, fields_map array and parameter_format_id
custom_parameter_values List of all Custom Parameter values with final value, fields_map array and parameter_format_id
info_field_values List of all Info Field values with final value, fields_map array and parameter_format_id
labels List of labels applied
short_url[clicks] Number of clicks on the short URL
short_url[url] Short URL for the Link
created_at Timestamp when the Link was created
updated_at Timestamp when the Link was last updated
created_by User who created the Link
created_by_api Whether the Link is created through an API
duplicate Returns true if another link with same long_url already exists in the project

Download QR code

QR code can be downloaded for either the fully tagged URL or the short URL.

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_I5bgXoK6OY/links/3885/qrcode?format=png" -X GET \
    -H "Content-Type: application/json" \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/links/:id/qrcode

Parameters

format: png
Name Description
project_id required Project ID starting with prj_
id required Link ID
format required Image format for the QR code. Accepted values are png or svg.
size Size of the QR code file. Accepted values are from 200 to 800.
transparency Applies transparent background to the QR code if possible. Accepted values are true or false.
url_type Type of URL to generate QR code for. Accepted values are long or short.
subtext Subtext to be displayed below the QR code. Maximum 30 characters.

Response

"[binary data]"

Mediums

List Medium Values

Get UTM Medium values

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_t2NgpEjVL9/mediums" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/mediums

Parameters

Name Description
project_id required Project ID starting with prj_
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "value": "blog-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "blog-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
value Medium tag
fields_map Fields Data saved for the this Medium Value
parameter_format_id Parameter Format ID used to save the Medium Value

Parameter Formats

List parameter formats

Get a list of Parameter Formats

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_qsEKSZM355/parameter_formats" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/parameter_formats

Parameters

Name Description
project_id required Project ID starting with prj_
items Number of items to be returned. This can range between 1 and 100. Default is 10.
page Specify the page number to get items that cannot be returned in a single request. Default is 1.

Response

{
  "data": [
    {
      "id": 601,
      "name": "Email Campaign Format",
      "separator": "-",
      "fields": [
        {
          "id": 1101,
          "name": "Interval",
          "description": null,
          "required": true,
          "type": "OptionField",
          "date_format": null,
          "constant_value": null,
          "prefix": null,
          "suffix": ":int",
          "option_values": [
            {
              "name": "weekly",
              "description": "Weekly newsletter",
              "position": 1
            },
            {
              "name": "monthly",
              "description": "Monthly newsletter",
              "position": 2
            },
            {
              "name": "yearly",
              "description": "",
              "position": 3
            }
          ]
        },
        {
          "id": 1102,
          "name": "Campaign Date",
          "description": null,
          "required": true,
          "type": "DateField",
          "date_format": "YYYY_MM_DD",
          "constant_value": null,
          "prefix": "date_",
          "suffix": null,
          "option_values": [

          ]
        },
        {
          "id": 1103,
          "name": "Headline",
          "description": null,
          "required": true,
          "type": "TextField",
          "date_format": null,
          "constant_value": null,
          "prefix": null,
          "suffix": null,
          "option_values": [

          ]
        },
        {
          "id": 1104,
          "name": "Headline",
          "description": null,
          "required": true,
          "type": "TextField",
          "date_format": null,
          "constant_value": null,
          "prefix": null,
          "suffix": null,
          "option_values": [

          ]
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
data An array of items
meta[page] Current page number
meta[has_more] true if more items are available on the next page. Otherwise false

Get a parameter format

Get a specific Parameter Format

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_l8CtmvHm5W/parameter_formats/602" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/parameter_formats/:parameter_format_id

Parameters

Name Description
project_id required Project ID starting with prj_
parameter_format_id required Parameter format id

Response

{
  "id": 602,
  "name": "Email Campaign Format",
  "separator": "-",
  "fields": [
    {
      "id": 1105,
      "name": "Interval",
      "description": null,
      "required": true,
      "type": "OptionField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": ":int",
      "option_values": [
        {
          "name": "weekly",
          "description": "Weekly newsletter",
          "position": 1
        },
        {
          "name": "monthly",
          "description": "Monthly newsletter",
          "position": 2
        },
        {
          "name": "yearly",
          "description": "",
          "position": 3
        }
      ]
    },
    {
      "id": 1106,
      "name": "Campaign Date",
      "description": null,
      "required": true,
      "type": "DateField",
      "date_format": "YYYY_MM_DD",
      "constant_value": null,
      "prefix": "date_",
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 1107,
      "name": "Headline",
      "description": null,
      "required": true,
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    },
    {
      "id": 1108,
      "name": "Headline",
      "description": null,
      "required": true,
      "type": "TextField",
      "date_format": null,
      "constant_value": null,
      "prefix": null,
      "suffix": null,
      "option_values": [

      ]
    }
  ]
}
Name Description
id Parameter format id
name Given name of the parameter format
separator Separator character used to join the fields
fields An array of field objects

Projects

List projects

Get a list of projects

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/

Parameters

Name Description
items Number of items to be returned. This can range between 1 and 100. Default is 10.
page Specify the page number to get items that cannot be returned in a single request. Default is 1.

Response

{
  "data": [
    {
      "id": "prj_iqYhY5jSTz",
      "name": "My project"
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
data An array of items
meta[page] Current page number
meta[has_more] true if more items are available on the next page. Otherwise false

Sources

List Source Values

Get UTM Source values

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_kgUxawjO2X/sources" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/sources

Parameters

Name Description
project_id required Project ID starting with prj_
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "value": "blog-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "blog-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
value Source tag
fields_map Fields Data saved for the this Source Value
parameter_format_id Parameter Format ID used to save the Source Value

Terms

List Term Values

Get UTM Term values

Request Endpoint

curl -g "https://api.terminusapp.com/v1/projects/prj_wPtiNOIxCC/terms" -X GET \
    -u YOUR_API_KEY:

GET /v1/projects/:project_id/terms

Parameters

Name Description
project_id required Project ID starting with prj_
page Specify the page number to get items that cannot be returned in a single request. Default is 1.
items Number of items to be returned. This can range between 1 and 100. Default is 10.

Response

{
  "data": [
    {
      "value": "blog-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "blog-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-1",
      "fields_map": [

      ],
      "parameter_format_id": null
    },
    {
      "value": "sale-2",
      "fields_map": [

      ],
      "parameter_format_id": null
    }
  ],
  "meta": {
    "page": 1,
    "has_more": false
  }
}
Name Description
value Term tag
fields_map Fields Data saved for the this Term Value
parameter_format_id Parameter Format ID used to save the Term Value

Errors

The Terminus API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You are not allowed to access this resource.
404 Not Found -- The specified resource could not be found.
429 Too Many Requests -- Your have hit the API rate limit. Try after some time.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
cURL