Introduction

This documentation is under review and is subject to change. Please check the Change Log to view any recent changes.

The Proposition API allows you to interact with various features in Proposition.

The API expects JSON input and returns a JSON response.

The test environment is available at https://alpha.propositionpro.com/l/api/{method}
The live environment is available at https://propositionpro.com/l/api/{method}

Rate Limiting: The API allows up to 60 requests per minute to each endpoint. Any requests over this will return a 429 - Too Many Requests.

Note that populating CRM records should be done in the order shown - you need to have created a CRM Company before creating a CRM Site for that company. You also need to have created a CRM Site before creating a CRM Contact.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://alpha.propositionpro.com/l/api/{method}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

Make sure to replace PROPOSITION_API_KEY with your API key.

Authorisation is via an API Token. To send the token in the request, there are two different options:

Pass the token in the URL: ?api_token=PROPOSITION_API_KEY
Pass the token in the request header: Authorization: Bearer PROPOSITION_API_KEY

You must replace PROPOSITION_API_KEY with your personal API key. This is only when using a User API Key. If you are using a Company API Key, please see below.

API Tokens issued by Tariffcom Ltd are either a Company API Token or a User API Token. If you are issued a Company API Token, you are required to send an additional parameter, either in the header, or the URL containing the Proposition Username.

Pass the token and username in the URL: ?api_token=COMPANY_API_KEY&proposition_username=PROPOSITION_USERNAME
Pass the token and username in the request header: Authorization: Bearer COMPANY_API_KEY\r\nproposition_username=PROPOSITION_USERNAME

You must replace COMPANY_API_KEY with your company API key and PROPOSITION_USERNAME with the current users Proposition Username. This is only required when using a Company API Key

Tokens are provided by Tariffcom Ltd.

Webhooks

Overview

proposal.created payload:

{
  "type": "proposal.created",
  "reference": "1082776",
  "payload": {
    "displayed_ref": "1082776v01N"
  }
}

proposal.status_changed payload:

{
  "type": "proposal.status_changed",
  "reference": "1082776",
  "payload": {
    "status": "Pending (Proposal approved)"
  }
}

account_change.created payload:

{
  "type": "account_change.created",
  "reference": "14202",
  "payload": {
    "base_request_no": "14202",
    "request_type": "User Name Change"
}
}

account_change.status_changed payload:

{
  "type": "account_change.status_changed",
  "reference": "14202-001",
  "payload": {
    "base_request_no" : "14202",
    "request_type" : "User Name Changed",
    "new_status" : "Closed",
    "request_no" : "14202-001"
  }
}

contract.sent payload:

{
  "type": "contract.sent",
  "reference": "1082776",
  "payload": {
    "reference": "1082776v01N"
  }
}

contract.email_opened payload:

{
  "type": "contract.email_opened",
  "reference": "782649",
  "payload": {
    "reference": "782649v01N"
  }
}

contract.link_opened payload:

{
  "type": "contract.link_opened",
  "reference": "1082776",
  "payload": {
    "reference": "1082776v01N"
  }
}

contract.signed payload:

{
  "type": "contract.signed",
  "reference": "1082776",
  "payload": {
    "reference": "1082776v01N"
  }
}

Webhooks are sent as a post request to the URL provided. The payload of the webhooks will vary depending on the type, however as a minimum will include the following fields:

type
reference
payload

For any proposal.* or contract.* webhooks, the reference will be the Proposal ID. For account_change.* webhooks, the reference will be either the Base Request Number, or the Request Number. Example payloads are shown to the right:

Get All Active Webhook URLs

This endpoint retrieves all currently active Webhook URLs:

curl "https://alpha.propositionpro.com/l/api/v2/webhooks" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

[
  {
    "id": 3,
    "url": "https://testurl.com/webhook",
    "event_types": "all",
    "header": "Authorization|Bearer ABC123",
    "retry_attempts": 10,
    "retry_wait_time_ms": 3600000,
    "notify_on_failure": 1,
    "notification_email": "mbowyer@tariffcom.com"
  }
]

This endpoint retrieves all currently active Webhook URLs.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/webhooks

Response Fields

Field	Data Type
id	int
url	varchar
event_types	varchar
header	varchar
retry_attempts	integer
retry_wait_time_ms	integer
notify_on_failure	boolean
notification_email	boolean

Add A New Webhook URL

This command adds a new Webhook URL:

{
  "url":"https://testurl.com/webhook",
  "event_types":"all",
  "header":"Authorization|Bearer ABC123",
  "retry_attempts":10,
  "retry_wait_time_ms":3600000,
  "notify_on_failure":true,
  "notification_email":"mbowyer@tariffcom.com"
}

The response will contain the request fields along with the new id of the created webhook:

{
  "id":4,
  "url":"https://testurl.com/webhook",
  "event_types":"all",
  "header":"Authorization|Bearer ABC123",
  "retry_attempts":10,
  "retry_wait_time_ms":3600000,
  "notify_on_failure":true,
  "notification_email":"mbowyer@tariffcom.com"
}

This endpoint creates a new Webhook URL

HTTP Request

POST https://alpha.propositionpro.com/l/api/v2/webhooks

Request Fields

Field	Data Type	Length	Required
url	text		Yes
event_types	text		Yes
header	text		No
retry_attempts	int	11	Yes
retry_wait_time_ms	bigint	20	Yes
notify_on_failure	boolean		Yes
notification_email	varchar	191	No *

* notification_email is required when notify_on_failure is set to true.

If the header field is populated, this will be sent as part of the header when the webhook is sent. The header should be a pipe separated key and value, for example: Authorization|Bearer ABC123

event_types should generally be set to all, however the valid types are

proposal.created
proposal.status_changed
account_change.created
account_change.status_changed
contract.sent
contract.email_opened
contract.link_opened
contract.signed

When sending multiple event_types, these should either be a comma or pipe separated list, for example:

proposal.created,proposal.status_changed
proposal_created|proposal.status_changed

Delete A Webhook URL

This command deletes the specified Webhook URL based on the ID passed in the URL.

curl "https://alpha.propositionpro.com/l/api/v2/webhooks/{webhook_id}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

This command deletes the specified Webhook URL based on the ID passed in the URL.

HTTP Request

DELETE https://alpha.propositionpro.com/l/api/v2/webhooks/{webhook_id}

CRM Companies

Get All CRM Companies

This command does not use any query parameters and returns all CRM Companies as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
  "current_page": 1,
  "data": [
    {
      "crm_company_id": 123456,
      "company_name": "ACME Inc",
      "company_type": "Private Limited Company (Ltd)",
      "status": "Customer",
      "company_reg_no": "12345678",
      "vat_reg_no": "",
      "address1": "123 Some Road",
      "address2": "",
      "address3": "",
      "address4": "Swansea",
      "county": "",
      "postcode": "TE7 5IN",
      "country": "",
      "tel_no": "01234567890",
      "fax_no": "01234567890",
      "web_address": "",
      "employees": "200",
      "third_party_crm_id": "ABC123",
      "third_party_id": "01234567",
      "third_party_sync_date": "2021-06-08 10:01:00"
    },
    {
      "crm_company_id": 123457,
      "company_name": "ACME Ltd",
      "company_type": "Private Limited Company (Ltd)",
      "status": "Customer",
      "company_reg_no": "12345679",
      "vat_reg_no": "",
      "address1": "123 Some Road",
      "address2": "",
      "address3": "",
      "address4": "Swansea",
      "county": "",
      "postcode": "TE7 5IN",
      "country": "",
      "tel_no": "01234567890",
      "fax_no": "01234567890",
      "web_address": "",
      "employees": "200",
      "third_party_crm_id": "ABC124",
      "third_party_id": "01234567",
      "third_party_sync_date": "2021-06-08 10:01:00"
    }
  ],
  "from": 1,
  "last_page": 2,
  "next_page_url": "https://alpha.propositionpro.com/l/api/v2/crm/companies?page=2",
  "path": "https://alpha.propositionpro.com/l/api/v2/crm/companies",
  "per_page": "2",
  "prev_page_url": null,
  "to": 2,
  "total": 4
}

This endpoint retrieves all CRM Companies.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/crm/companies

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	crm_company_id	string	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
crm_company_id	int	6	No
company_name	varchar	100	No
company_type	varchar	50	Yes
status	varchar	50	Yes
company_reg_no	varchar	10	Yes
vat_reg_no	varchar	15	Yes
address1	varchar	40	Yes
address2	varchar	40	Yes
address3	varchar	40	Yes
address4	varchar	40	Yes
county	varchar	40	Yes
postcode	varchar	10	Yes
country	varchar	40	Yes
tel_no	varchar	15	Yes
fax_no	varchar	15	Yes
web_address	varchar	100	Yes
employees	varchar	10	Yes
third_party_crm_id	varchar	50	Yes
third_party_id	varchar	50	Yes
third_party_sync_date	datetime		Yes

Get Single CRM Company

This command returns a single CRM Company as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"


{
  "crm_company_id": 123456,
  "company_name": "ACME Inc",
  "company_type": "Private Limited Company (Ltd)",
  "status": "Customer",
  "company_reg_no": "12345678",
  "vat_reg_no": "",
  "address1": "123 Some Road",
  "address2": "",
  "address3": "",
  "address4": "Swansea",
  "county": "",
  "postcode": "TE7 5IN",
  "country": "",
  "tel_no": "01234567890",
  "fax_no": "01234567890",
  "web_address": "",
  "employees": "200",
  "third_party_crm_id": "ABC124",
  "third_party_id": "01234567",
  "third_party_sync_date": "2021-06-08 10:01:00"
}

This endpoint retrieves a single CRM Company

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}

Response Fields

Field	Data Type	Length	Nullable
crm_company_id	int	6	No
company_name	varchar	100	No
company_type	varchar	50	Yes
status	varchar	50	Yes
company_reg_no	varchar	10	Yes
vat_reg_no	varchar	15	Yes
address1	varchar	40	Yes
address2	varchar	40	Yes
address3	varchar	40	Yes
address4	varchar	40	Yes
county	varchar	40	Yes
postcode	varchar	10	Yes
country	varchar	40	Yes
tel_no	varchar	15	Yes
fax_no	varchar	15	Yes
web_address	varchar	100	Yes
employees	varchar	10	Yes
third_party_crm_id	varchar	50	Yes
third_party_id	varchar	50	Yes
third_party_sync_date	datetime		Yes

Create New CRM Company

This command inserts a new CRM Company into Proposition from a JSON Payload:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

[
    {
        "company_name": "AMCE Inc",
        "unique_name": "AMCE Inc",
        "company_type": "Limited Company",
        "status": "Warm Lead",
        "company_reg_no": "12345678",
        "vat_reg_no": "",
        "address1": "123 Test Road",
        "address2": "Alsager",
        "address3": "Stoke-On-Trent",
        "address4": "",
        "county": "Staffordshire",
        "postcode": "ST7 2EE",
        "country": "United Kingdom",
        "tel_no": "07777777777",
        "fax_no": "",
        "web_address": "https://www.acme.inc",
        "linked_in": "",
        "twitter": "",
        "notes": "",
        "bank_acc_name": "ACME INC",
        "bank_sort_code": "010101",
        "bank_acc_no": "12341234",
        "employees": "< 5",
        "third_party_crm_id": "ABC123456789"
    }
]

The response will contain the request fields along with the new crm_company_id of the inserted company:

[
    {
        "company_name": "AMCE Inc",
        "unique_name": "AMCE Inc",
        "company_type": "Limited Company",
        "status": "Warm Lead",
        "company_reg_no": "12345678",
        "vat_reg_no": "",
        "address1": "123 Test Road",
        "address2": "Alsager",
        "address3": "Stoke-On-Trent",
        "address4": "",
        "county": "Staffordshire",
        "postcode": "ST7 2EE",
        "country": "United Kingdom",
        "tel_no": "07777777777",
        "fax_no": "",
        "web_address": "https://www.acme.inc",
        "linked_in": "",
        "twitter": "",
        "notes": "",
        "bank_acc_name": "ACME INC",
        "bank_sort_code": "010101",
        "bank_acc_no": "12341234",
        "employees": "< 5",
        "third_party_crm_id": "ABC123456789",
        "crm_company_id": 359398
    }
]

If there are errors for any of the requests, the errors field will be populated:

[
    {
        "company_name": "AMCE Inc",
        "unique_name": "AMCE Inc",
        "company_type": "Limited Company",
        "status": "Warm Lead",
        "company_reg_no": "12345678",
        "vat_reg_no": "",
        "address1": "123 Test Road",
        "address2": "Alsager",
        "address3": "Stoke-On-Trent",
        "address4": "",
        "county": "Staffordshire",
        "postcode": "ST7 2EE",
        "country": "United Kingdom",
        "tel_no": "07777777777",
        "fax_no": "",
        "web_address": "https://www.acme.inc",
        "linked_in": "",
        "twitter": "",
        "notes": "",
        "bank_acc_name": "ACME INC",
        "bank_sort_code": "010101",
        "bank_acc_no": "12341234",
        "employees": "< 5",
        "third_party_crm_id": "ABC123456789",
        "errors": {
            "third_party_crm_id": [
                "The third party crm id has already been taken."
            ]
        }
    }
]

This endpoint creates one or more CRM Companies

HTTP Request

POST https://alpha.propositionpro.com/l/api/v2/crm/companies

Request Fields

Field	Data Type	Length	Required
company_name	varchar	100	Yes
unique_name	varchar	100	Yes
company_type	enum: See Below	50	No
status	varchar	50	No
company_reg_no	varchar	10	No
vat_reg_no	varchar	15	No
address1	varchar	40	No
address2	varchar	40	No
address3	varchar	40	No
address4	varchar	40	No
county	varchar	40	No
postcode	varchar	10	No
country	varchar	40	No
tel_no	varchar	15	No
fax_no	varchar	15	No
web_address	varchar	100	No
linked_in	varchar	100	No
twitter	varchar	100	No
notes	varchar	100	No
bank_acc_name	varchar	32	No
bank_sort_code	varchar	6	No
bank_acc_no	varchar	8	No
third_party_crm_id	varchar	50	No
employees	varchar	10	No

Values for the company_type field:

Sole Trader
Partnership
Private Limited Company (Ltd)
Public Limited Company (plc)
Limited Liability Partnership (LLP)
Not for Profit Organisation
Consumer

CRM Sites

Get All CRM Sites for a CRM Company

This command does not use any query parameters and returns all CRM Sites as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/sites" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "current_page": 1,
    "data": [
        {
            "crm_site_id": 191507,
            "site_description": "Main Site",
            "address1": "123 Test Road",
            "address2": "Alsager",
            "address3": "Stoke-On-Trent",
            "address4": "",
            "county": "Staffordshire",
            "postcode": "TE5 7IN",
            "country": "United Kingdom",
            "tel_no": "07777777777",
            "fax_no": "",
            "registered_office": 1,
            "third_party_crm_id": "ABC12345",
            "address_full": "123 Test Road, Alsager, Stoke-On-Trent"
        }
    ],
    "from": 1,
    "last_page": 1,
    "next_page_url": null,
    "path": "https://alpha.propositionpro.com/l/api/v2/crm/companies/359397/sites",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1,
    "total": 1
}

This endpoint retrieves all CRM Sites.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/sites

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	crm_site_id	string	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
crm_site_id	int	10	No
site_description	varchar	40	No
address1	varchar	40	Yes
address2	varchar	40	Yes
address3	varchar	40	Yes
address4	varchar	40	Yes
county	varchar	40	Yes
postcode	varchar	10	No
country	varchar	40	Yes
tel_no	varchar	15	Yes
fax_no	varchar	15	Yes
registered_office	boolean		Yes
third_party_crm_id	varchar	50	Yes
address_full	varchar	210	Yes

Note: The address_full field is a concatenated field based on the address1, address2, address3 and address4 fields.

Get Single CRM Site

This command returns a single CRM Site as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/sites/{crm_site_id}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "crm_site_id": 191507,
    "site_description": "Main Site",
    "address1": "123 Test Road",
    "address2": "Alsager",
    "address3": "Stoke-On-Trent",
    "address4": "",
    "county": "Staffordshire",
    "postcode": "TE5 7IN",
    "country": "United Kingdom",
    "tel_no": "07777777777",
    "fax_no": "",
    "registered_office": 1,
    "third_party_crm_id": "ABC12345",
    "address_full": "123 Test Road, Alsager, Stoke-On-Trent"
}

This endpoint retrieves a single CRM Site

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/sites/{crm_site_id}

Response Fields

Field	Data Type	Length	Nullable
crm_site_id	int	10	No
site_description	varchar	40	No
address1	varchar	40	Yes
address2	varchar	40	Yes
address3	varchar	40	Yes
address4	varchar	40	Yes
county	varchar	40	Yes
postcode	varchar	10	No
country	varchar	40	Yes
tel_no	varchar	15	Yes
fax_no	varchar	15	Yes
registered_office	boolean		Yes
third_party_crm_id	varchar	50	Yes
address_full	varchar	210	Yes

Note: The address_full field is a concatenated field based on the address1, address2, address3 and address4 fields.

Create New CRM Site

This command inserts a new CRM Site into Proposition from a JSON Payload:

[
    {
        "company_name": "ACME Inc",
        "site_description": "Main Site",
        "address1": "123 Test Road",
        "address2": "Alsager",
        "address3": "Stoke-On-Trent",
        "address4": "",
        "county": "Staffordshire",
        "postcode": "TE5 7IN",
        "country": "United Kingdom",
        "tel_no": "07777777777",
        "fax_no": null,
        "registered_office": true,
        "third_party_crm_id": "ABC12345"
    }
]

The response will contain the request fields along with the new crm_site_id of the inserted site:

[
    {
        "company_name": "ACME Inc",
        "site_description": "Main Site",
        "address1": "123 Test Road",
        "address2": "Alsager",
        "address3": "Stoke-On-Trent",
        "address4": "",
        "county": "Staffordshire",
        "postcode": "TE5 7IN",
        "country": "United Kingdom",
        "tel_no": "07777777777",
        "fax_no": null,
        "registered_office": true,
        "third_party_crm_id": "ABC12345",
        "crm_site_id": 142502
    }
]

If there are errors for any of the requests, the errors field will be populated:

[
    {
        "company_name": "ACME Inc",
        "site_description": "Main Site",
        "address1": "123 Test Road",
        "address2": "Alsager",
        "address3": "Stoke-On-Trent",
        "address4": "",
        "county": "Staffordshire",
        "postcode": "TE5 7IN",
        "country": "United Kingdom",
        "tel_no": "07777777777",
        "fax_no": null,
        "registered_office": true,
        "third_party_crm_id": "ABC12345",
        "errors": {
            "third_party_crm_id": [
                "The third party crm id has already been taken."
            ]
        }
    }
]

This endpoint creates one or more CRM Sites

HTTP Request

POST https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/sites

Request Fields

Field	Data Type	Length	Required
company_name	varchar	100	Yes
site_description	varchar	40	Yes
address1	varchar	40	No
address2	varchar	40	No
address3	varchar	40	No
address4	varchar	40	No
county	varchar	40	No
postcode	varchar	10	Yes
country	varchar	40	No
tel_no	varchar	15	No
fax_no	varchar	15	No
registered_office	boolean		No
third_party_crm_id	varchar	50	Yes

CRM Contacts

Get All CRM Contacts for a CRM Company

This command does not use any query parameters and returns all CRM Contacts as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/contacts" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "current_page": 1,
    "data": [
        {
            "crm_contact_id": 142502,
            "title": "Mr",
            "first_name": "John",
            "middle_name": "",
            "surname": "Smith",
            "gender": "Male",
            "job_title": "Developer",
            "department": "IT",
            "email": "john@smith.com",
            "mobile_tel": "07777777777",
            "office_tel": "",
            "home_tel": "",
            "date_left_company": null,
            "third_party_crm_id": "ABC12345",
            "contact_name": "John Smith",
            "full_name": "John Smith"
        }
    ],
    "from": 1,
    "last_page": 1,
    "next_page_url": null,
    "path": "https://alpha.propositionpro.com/l/api/v2/crm/companies/12345/contacts",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1,
    "total": 1
}

This endpoint retrieves all CRM Contacts.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/contacts

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	crm_contact_id	string	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
crm_contact_id	int	10	No
title	varchar	20	No
first_name	varchar	30	Yes
middle_name	varchar	30	Yes
surname	varchar	30	Yes
gender	varchar	10	Yes
job_title	varchar	30	Yes
department	varchar	30	Yes
email	varchar	70	Yes
mobile_tel	varchar	15	Yes
office_tel	varchar	15	Yes
home_tel	varchar	15	Yes
date_left_company	date		Yes
third_party_crm_id	varchar	50	Yes
contact_name	varchar	90	Yes
full_name	varchar	90	Yes

Note: The contact_name and full_name fields are concatenated fields based on the first_name, middle_name and surname fields.

Get Single CRM Contact

This command returns a single CRM Contact as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/contacts/{crm_contact_id}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "crm_contact_id": 142502,
    "title": "Mr",
    "first_name": "John",
    "middle_name": "",
    "surname": "Smith",
    "gender": "Male",
    "job_title": "Developer",
    "department": "IT",
    "email": "john@smith.com",
    "mobile_tel": "07777777777",
    "office_tel": "",
    "home_tel": "",
    "date_left_company": null,
    "third_party_crm_id": "ABC12345",
    "contact_name": "John Smith",
    "full_name": "John Smith"
}

This endpoint retrieves a single CRM Company

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/contacts/{crm_contact_id}

Response Fields

Field	Data Type	Length	Nullable
crm_contact_id	int	10	No
title	varchar	20	No
first_name	varchar	30	Yes
middle_name	varchar	30	Yes
surname	varchar	30	Yes
gender	varchar	10	Yes
job_title	varchar	30	Yes
department	varchar	30	Yes
email	varchar	70	Yes
mobile_tel	varchar	15	Yes
office_tel	varchar	15	Yes
home_tel	varchar	15	Yes
date_left_company	date		Yes
third_party_crm_id	varchar	50	Yes
contact_name	varchar	90	Yes
full_name	varchar	90	Yes

Note: The contact_name and full_name fields are concatenated fields based on the first_name, middle_name and surname fields.

Create New CRM Contact

This command inserts a new CRM Contact into Proposition from a JSON Payload:

[
    {
        "title": "Mr",
        "first_name": "John",
        "middle_name": "",
        "surname": "Smith",
        "gender": "Male",
        "job_title": "Developer",
        "department": "IT",
        "manager": "James Smith",
        "crm_site_id": 12345,
        "email": "john@smith.com",
        "mobile_tel": "07777777777",
        "office_tel": "",
        "home_tel": "",
        "date_left_company": null,
        "third_party_crm_id": "ABC12345"
    }
]

The response will contain the request fields along with the new crm_contact_id of the inserted contact:

[
    {
        "title": "Mr",
        "first_name": "John",
        "middle_name": "",
        "surname": "Smith",
        "gender": "Male",
        "job_title": "Developer",
        "department": "IT",
        "manager": "James Smith",
        "crm_site_id": 12345,
        "email": "john@smith.com",
        "mobile_tel": "07777777777",
        "office_tel": "",
        "home_tel": "",
        "date_left_company": null,
        "third_party_crm_id": "ABC12345",
        "crm_contact_id": 142502
    }
]

If there are errors for any of the requests, the errors field will be populated:

[
    {
        "title": "Mr",
        "first_name": "John",
        "middle_name": "",
        "surname": "Smith",
        "gender": "Male",
        "job_title": "Developer",
        "department": "IT",
        "email": "john@smith.com",
        "mobile_tel": "07777777777",
        "office_tel": "",
        "home_tel": "",
        "date_left_company": null,
        "third_party_crm_id": "ABC12345",
        "errors": {
            "crm_site_id": [
                "The crm site id field is required."
            ],
            "third_party_crm_id": [
                "The third party crm id has already been taken."
            ]
        }
    }
]

This endpoint creates one or more CRM Contacts

HTTP Request

POST https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/contacts

Request Fields

Field	Data Type	Length	Required
title	varchar	20	No
first_name	varchar	30	Yes
middle_name	varchar	30	No
surname	varchar	30	Yes
gender	varchar	10	No
job_title	varchar	30	No
department	varchar	30	No
manager	varchar	30	No
crm_site_id	int	10	Yes
email	varchar	70	Yes
mobile_tel	varchar	15	No
office_tel	varchar	15	No
home_tel	varchar	15	No
date_left_company	date		No
third_party_crm_id	varchar	50	Yes

CRM Mobiles

Get All CRM Mobiles for a CRM Company

This command does not use any query parameters and returns all CRM Mobiles as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/mobiles" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "current_page": 1,
    "data": [
        {
            "crm_mobile_id": 215406,
            "status": null,
            "type": "New Connection",
            "number": "07777777777",
            "connection_date": "21-03-2019",
            "eoc_date": "21-03-2021",
            "username": "John Smith",
            "handset": "none",
            "current_network": "O2",
            "tariff": "Business 500 Sharer [new] (24m)",
            "sim": "8944121212121212121",
            "imei": "351015151515155",
            "pac": "ABC123123",
            "acc_no": "12345678",
            "third_party_crm_id": "ABC12345"
        }
    ],
    "from": 1,
    "last_page": 1,
    "next_page_url": null,
    "path": "https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/mobiles",
    "per_page": 50,
    "prev_page_url": null,
    "to": 1,
    "total": 1
}

This endpoint retrieves all CRM Mobiles.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/mobiles

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	crm_mobile_id	string	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
crm_mobile_id	int	10	No
status	varchar	40	Yes
type	varchar	40	Yes
number	varchar	15	Yes
connection_date	date		Yes
eoc_date	date		Yes
username	varchar	30	Yes
handset	varchar	40	Yes
current_network	varchar	40	Yes
tariff	varchar	100	Yes
sim	varchar	19	Yes
imei	varchar	15	Yes
pac	varchar	40	Yes
acc_no	varchar	40	Yes
third_party_crm_id	varchar	50	Yes

Get Single CRM Mobile

This command returns a single CRM Mobile as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/mobiles/{crm_mobile_id}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "crm_mobile_id": 215406,
    "status": null,
    "type": "New Connection",
    "number": "07777777777",
    "connection_date": "21-03-2019",
    "eoc_date": "21-03-2021",
    "username": "John Smith",
    "handset": "none",
    "current_network": "O2",
    "tariff": "Business 500 Sharer [new] (24m)",
    "sim": "8944121212121212121",
    "imei": "351015151515155",
    "pac": "ABC123123",
    "acc_no": "12345678",
    "third_party_crm_id": "ABC12345",
}

This endpoint retrieves a single CRM Mobile

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/mobiles/{crm_mobile_id}

Response Fields

Field	Data Type	Length	Nullable
crm_mobile_id	int	10	No
status	varchar	40	Yes
type	varchar	40	Yes
number	varchar	15	Yes
connection_date	date		Yes
eoc_date	date		Yes
username	varchar	30	Yes
handset	varchar	40	Yes
current_network	varchar	40	Yes
tariff	varchar	100	Yes
sim	varchar	19	Yes
imei	varchar	15	Yes
pac	varchar	40	Yes
acc_no	varchar	40	Yes
third_party_crm_id	varchar	50	Yes

Create New CRM Mobile

This command inserts a new CRM Mobile into Proposition from a JSON Payload:

[
    {
        "status": "Active",
        "type": "Upgrade",
        "number": "07777777777",
        "connection_date": "01-06-2021",
        "eoc_date": "01-06-2023",
        "username": "John Smith",
        "handset": "iPhone 12 Pro Max 512GB",
        "current_supplier": "Unknown",
        "current_network": "O2",
        "tariff": "Business 500 Sharer [new] (24m)",
        "sim": "8944121212121212121",
        "imei": "351015151515155",
        "notes": "This is a note",
        "pac": "ABC12312",
        "roaming": false,
        "band": null,
        "auto_disconnect": true,
        "acc_no": "12345678",
        "description": "This is a description",
        "third_party_crm_id": "ABC12345",
    }
]

The response will contain the request fields along with the new crm_mobile_id of the inserted Mobile:

[
    {
        "status": "Active",
        "type": "Upgrade",
        "number": "07777777777",
        "connection_date": "01-06-2021",
        "eoc_date": "01-06-2023",
        "username": "John Smith",
        "handset": "iPhone 12 Pro Max 512GB",
        "current_supplier": "Unknown",
        "current_network": "O2",
        "tariff": "Business 500 Sharer [new] (24m)",
        "sim": "8944121212121212121",
        "imei": "351015151515155",
        "notes": "This is a note",
        "pac": "ABC12312",
        "roaming": false,
        "band": null,
        "auto_disconnect": true,
        "acc_no": "12345678",
        "description": "This is a description",
        "third_party_crm_id": "ABC12345",
        "crm_mobile_id": 142502
    }
]

If there are errors for any of the requests, the errors field will be populated:

[
    {
        "status": "Active",
        "type": "Upgrade",
        "number": "07777777777",
        "connection_date": "01-06-2021",
        "eoc_date": "01-06-2023",
        "username": "John Smith",
        "handset": "iPhone 12 Pro Max 512GB",
        "current_supplier": "Unknown",
        "current_network": "O2",
        "tariff": "Business 500 Sharer [new] (24m)",
        "sim": "8944121212121212121",
        "imei": "351015151515155",
        "notes": "This is a note",
        "pac": "ABC12312",
        "roaming": false,
        "band": null,
        "auto_disconnect": true,
        "acc_no": "12345678",
        "description": "This is a description",
        "third_party_crm_id": "ABC12345",
        "errors": {
            "third_party_crm_id": [
                "The third party crm id has already been taken."
            ]
        }
    }
]

This endpoint creates one or more CRM Mobiles

HTTP Request

POST https://alpha.propositionpro.com/l/api/v2/crm/companies/{crm_company_id}/mobiles

Request Fields

Field	Data Type	Length	Required
status	varchar	40	No
type	varchar	40	No
number	varchar	15	No
connection_date	date		No
eoc_date	date		No
username	varchar	30	No
handset	varchar	40	No
current_supplier	varchar	40	No
current_network	varchar	40	No
tariff	varchar	100	No
sim	varchar	19	No
imei	varchar	15	No
notes	varchar	100	No
pac	varchar	40	No
roaming	boolean		No
band	varchar	40	No
auto_disconnect	boolean		No
acc_no	varchar	40	No
description	varchar	40	No
third_party_crm_id	varchar	50	Yes

Proposals

Get All Proposals

This command does not use any query parameters and returns all Proposals as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/proposals" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
  "current_page": 1,
  "data": [
    {
      "proposal_id": 9655,
      "crm_company_id": 123456,
      "crm_contact_id": 123456,
      "company_name": "Sample Company Ltd",
      "presented_to": "Mr Eric  McCabe",
      "created": "2013-01-28 17:19:22",
      "status": 7,
      "status_name": "Contract Email Received",
      "win_probability": 0,
      "displayed_ref": "19160v01N",
      "opportunity": 0,
      "in_pipeline": 1,
      "coterminous": 0,
      "fully_connected": 1,
      "funding_code": null
    },
    {
      "proposal_id": 9656,
      "crm_company_id": 123456,
      "crm_contact_id": 123456,
      "company_name": "Sample Company Ltd",
      "presented_to": "Mr Eric  McCabe",
      "created": "2013-01-28 17:21:22",
      "status": 7,
      "status_name": "Contract Email Received",
      "win_probability": 0,
      "displayed_ref": "19161v01N",
      "opportunity": 0,
      "in_pipeline": 1,
      "coterminous": 0,
      "fully_connected": 1,
      "funding_code": null
    }
  ],
  "from": 1,
  "last_page": 1,
  "next_page_url": null,
  "path": "https://alpha.propositionpro.com/l/api/v2/proposals",
  "per_page": 50,
  "prev_page_url": null,
  "to": 2,
  "total": 2
}

This command uses both the created and in_pipeline query parameters and returns matching Proposals as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/proposals?created=2013-01-28&in_pipeline=true" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
  "current_page": 1,
  "data": [
    {
      "proposal_id": 9655,
      "crm_company_id": 123456,
      "crm_contact_id": 123456,
      "company_name": "Sample Company Ltd",
      "presented_to": "Mr Eric  McCabe",
      "created": "2013-01-28 17:19:22",
      "status": 7,
      "status_name": "Contract Email Received",
      "win_probability": 0,
      "displayed_ref": "19160v01N",
      "opportunity": 0,
      "in_pipeline": 1,
      "coterminous": 0,
      "fully_connected": 1,
      "funding_code": null
    }
  ],
  "from": 1,
  "last_page": 2,
  "next_page_url": "https://alpha.propositionpro.com/l/api/v2/proposals?created=2013-01-28&in_pipeline=true&page=2",
  "path": "https://alpha.propositionpro.com/l/api/v2/proposals",
  "per_page": 1,
  "prev_page_url": null,
  "to": 1,
  "total": 2
}

This endpoint retrieves all proposals.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/proposals

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	proposal_id	string	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.
proposal_id	null	integer	If set, only return proposals where the Proposal ID matches.
company_name	null	string	If set, only return proposals where the Company Name matches.
created	null	date	If set, only return proposals where the date matches. Format YYYY-MM-DD.
status	null	integer	If set, only return proposals where the Status ID matches.
status_name	null	string	If set, only return proposals where the Status Name matches.
win_probability	null	integer	If set, only return proposals where the win probability matches (integer).
displayed_ref	null	string	If set, only returns proposals where the displayed reference matches.
opportunity	null	boolean	If set to true, only return proposals that are opportunities.
in_pipeline	null	boolean	If set to true, only return proposals that are in the pipeline.
fully_connected	null	boolean	If set to true, only return proposals that are fully connected.
funding_code	null	string	If set, only return proposals where the funding code matches.

Response Fields

Field	Data Type	Length	Nullable
proposal_id	int	10	No
crm_company_id	int	10	No
crm_contact_id	int	10	No
company_name	varchar	100	No
presented_to	varchar	90	No
created	datetime		No
status	int	3	No
status_name	varchar	50	No
win_probability	int	3	No
displayed_ref	varchar	30	Yes
opportunity	tinyint	1	Yes
in_pipeline	tinyint	1	No
coterminous	tinyint	1	Yes
fully_connected	tinyint	1	No
funding_code	varchar	10	Yes

Get Single Proposal

curl "https://alpha.propositionpro.com/l/api/v2/proposal/{proposal_id}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

The above command returns JSON structured like this:

{
  "proposal_id": 781654,
  "crm_company_id": 165831,
  "crm_contact_id": 0,
  "company_name": "Testing Account",
  "proposal_status": "Pending (Proposal approved)",
  "expected_connection_date": "2021-07-16",
  "win_probability": 20,
  "products": [
    {
      "product_id": 15258,
      "product_code": "MA1AAD",
      "name": "O2 Business 1GB [new]",
      "quantity": 1,
      "term": 24,
      "lead_rental": 20,
      "atc_amount": 0,
      "unit_net_cost": 20,
      "total_monthly_cost": 20,
      "total_one_off_cost": 0
    }
  ],
  "boltons": [
    {
      "bolton_id": 6326,
      "product_code": "PCAP0",
      "name": "&pound;0 spend cap per connection",
      "quantity": 1,
      "term": 1,
      "rental": 0,
      "atc_amount": 0,
      "unit_net_cost": 0,
      "total_monthly_cost": 0,
      "total_one_off_cost": 0
    },
    {
      "bolton_id": 4445,
      "product_code": "24HRD",
      "name": "Rest of World 24 Hour Pass Unlimited @ £7.50/pass",
      "quantity": 1,
      "term": 1,
      "rental": 0,
      "atc_amount": 0,
      "unit_net_cost": 0,
      "total_monthly_cost": 0,
      "total_one_off_cost": 0
    }
  ],
  "hardware": []
}

This endpoint retrieves the proposal details.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/proposal/{proposal_id}

Response Fields (Proposal)

Field	Data Type	Length	Nullable
proposal_id	int	10	No
crm_company_id	int	10	No
crm_contact_id	int	10	No
company_name	varchar	100	No
proposal_status	varchar		No
expected_connection_date	date		No
win_probability	int	3	No
products	array of Products		Yes
boltons	array of Boltons		Yes
hardware	array of Hardware		Yes

Response Fields (Products)

Field	Data Type	Length	Nullable
product_id	int		No
product_code	varchar	30	No
name	varchar	100	No
quantity	int		No
term	int		No
lead_rental	decimal	8,2	No
atc_amount	decimal	8,2	No
unit_net_cost	decimal	8,2	No
total_monthly_cost	decimal	8,2	No
total_one_off_cost	decimal	8,2	No

Response Fields (Boltons)

Field	Data Type	Length	Nullable
bolton_id	int		No
product_code	varchar	30	No
name	varchar	100	No
quantity	int		No
term	int		No
rental	decimal	8,2	No
atc_amount	decimal	8,2	No
unit_net_cost	decimal	8,2	No
total_monthly_cost	decimal	8,2	No
total_one_off_cost	decimal	8,2	No

Response Fields (Hardware)

Field	Data Type	Length	Nullable
hardware_id	int		No
product_code	varchar	30	No
name	varchar	100	No
quantity	int		No
unit_rrp	decimal	8,2	No
unit_net_cost	decimal	8,2	No
total_one_off_cost	decimal	8,2	No

Create Proposal

This command creates a new Proposal

curl "https://alpha.propositionpro.com/l/api/v2/proposals" \
  -H "Authorization: Bearer PROPOSITION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"crm_company_id":100000,"crm_contact_id":200000,"remaining_tenure":null,"no_of_employees":50,"direct_debit":0,"itemised_paper_billing":0,"row_data_pass_rate":7.5,"international_call_discount":0,"current_mobile_spend":0,"expected_connection_date":"2021-05-01","products":[{"product_code":"ABC123","quantity":"15","cost":"25.00","term":"24","boltons":[{"product_code":"BOL001","quantity":"10","cost":"10.00","term":"1"},{"product_code":"BOL002","quantity":"5","cost":"15.00","term":"24"}]},{"product_code":"XYZ987","quantity":"10","cost":"32.00","term":"24","boltons":[{"product_code":"BOL999","quantity":"10","cost":"2.00","term":"24"},{"product_code":"BOL555","quantity":"7","cost":"7.00","term":"24"}]}]}'

{
  "crm_company_id": 100000,
  "crm_contact_id": 200000,
  "remaining_tenure": null,
  "no_of_employees": 50,
  "direct_debit": "yes",
  "itemised_paper_billing": "yes_1_mpn_month",
  "row_data_pass_rate": 7.50,
  "international_call_discount": 0,
  "current_mobile_spend": 0,
  "expected_connection_date": "2021-05-01",
  "products": [
    {
      "product_id": "234567", 
      "quantity": "15", 
      "cost": "25.00", 
      "term": "24", 
      "boltons": [
        {
          "bolton_id": "12345", 
          "quantity": "10",
          "cost": "10.00", 
          "term": "1"
        }, 
        {
          "bolton_id": "12346", 
          "quantity": "5", 
          "cost": "15.00", 
          "term": "24"
        } 
      ]
    }
  ]
}

The response will return the newly created Proposal:

{
    "proposal_id": 123456,
    "crm_company_id": 123456,
    "crm_contact_id": 123456,
    "company_name": "ACME Inc",
    "proposal_status": "Pending",
    "expected_connection_date": "2021-01-31",
    "win_probability": 0,
    "products": [
      {
        "product_id": 5263,
        "product_code": "ABC123",
        "name": "O2 Business with Shared Data [upgrade\/re-sign]",
        "quantity": 1,
        "term": 24,
        "unit_rrp": 21,
        "unit_credit": 0,
        "unit_net_cost": 21,
        "total_monthly_cost": 21,
        "total_one_off_cost": 0,
        "legacy": false,
        "basket_product_id": 12345
      }
    ],
    "boltons": [
      {
        "bolton_id": 5583,
        "product_code": "BOL001",
        "name": "Secondary user - Unlimited Calls\/texts [new] ",
        "quantity": 5,
        "term": 24,
        "unit_rrp": 21,
        "unit_credit": 0,
        "unit_net_cost": 21,
        "total_monthly_cost": 105,
        "total_one_off_cost": 0,
        "legacy": false,
        "basket_bolton_id": 12346
      }, 
      {
        "bolton_id": 2547,
        "product_code": "BOL002",
        "name": "20GB Shared Data",
        "quantity": 1,
        "term": 24,
        "unit_rrp": 120,
        "unit_credit": 0,
        "unit_net_cost": 120,
        "total_monthly_cost": 120,
        "total_one_off_cost": 0,
        "legacy": false,
        "basket_bolton_id": 12347
      }
    ]
}

HTTP Request

POST https://alpha.propositionpro.com/l/api/v2/proposals

Parameters (Proposal)

Parameter	Field Type	Length	Required
crm_company_id	int	10	Yes
crm_contact_id	int	10	Yes
remaining_tenure	int	3	No
no_of_employees	int	6	No
direct_debit	varchar	50	Yes - either 'yes' or 'no_250'
itemised_paper_billing	varchar	50	Yes - either 'no' or 'yes_1_mpn_month'
row_data_pass_rate	decimal	10,2	No
international_call_discount	decimal	10,2	No
current_mobile_spend	decimal	10,2	No
expected_connection_date	date		Yes

Parameters (Products)

Parameter	Field Type	Length	Required
product_id	int	10	Yes
quantity	int	6	Yes
cost	decimal	10,6	Yes
term	int	6	Yes

Parameters (Boltons)

Only required if boltons are being added to a product.

Parameter	Field Type	Length	Required
bolton_id	int	10	Yes
quantity	int	6	Yes
cost	decimal	10,6	Yes
term	int	6	Yes

Response Fields (Proposal)

Field	Data Type	Length	Nullable
proposal_id	int	10	No
crm_company_id	int	10	No
crm_contact_id	int	10	No
company_name	varchar	100	No
proposal_status	varchar		No
expected_connection_date	date		No
win_probability	int	3	No
products	array of Products		Yes
boltons	array of Boltons		Yes
hardware	array of Hardware		Yes

Response Fields (Products)

Field	Data Type	Length	Nullable
product_id	int		No
product_code	varchar	30	No
name	varchar	100	No
quantity	int		No
term	int		No
unit_rrp	decimal	8,2	No
unit_credit	decimal	8,2	No
unit_net_cost	decimal	8,2	No
total_monthly_cost	decimal	8,2	No
total_one_off_cost	decimal	8,2	No
legacy	boolean		No
basket_product_id	int		No

Response Fields (Boltons)

Field	Data Type	Length	Nullable
bolton_id	int		No
product_code	varchar	30	No
name	varchar	100	No
quantity	int		No
term	int		No
unit_rrp	decimal	8,2	No
unit_credit	decimal	8,2	No
unit_net_cost	decimal	8,2	No
total_monthly_cost	decimal	8,2	No
total_one_off_cost	decimal	8,2	No
legacy	boolean		No
basket_bolton_id	int		No

Tariffs & Boltons

Get All Tariffs

This command does not use any query parameters and returns all Tariffs as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/tariffs" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "current_page": 1,
    "data": [
        {
            "product_id": 1,
            "tariff": "Q27QAA",
            "tariff_description": "Business Share 500 (new,24m)",
            "data_amount": "0.00",
            "price": "27.82",
            "package": "P5SAAS",
            "package_iphone": "P5SAAS",
            "data_description": null,
            "minimum_contract_length": 24,
            "bcad": null,
            "spend_cap_available": null,
            "5g_bolton_compatibility": null
        },
        {
            "product_id": 2,
            "tariff": "Q27QAC",
            "tariff_description": "Business Share 1,300 (new,24m)",
            "data_amount": "0.00",
            "price": "50.09",
            "package": "P5SAAU",
            "package_iphone": "P5SAAU",
            "data_description": null,
            "minimum_contract_length": 24,
            "bcad": null,
            "spend_cap_available": null,
            "5g_bolton_compatibility": null
        }
    ],
    "from": 1,
    "last_page": 512,
    "next_page_url": "https://alpha.propositionpro.com/l/api/v2/tariffs&page=2",
    "path": "https://alpha.propositionpro.com/l/api/v2/tariffs",
    "per_page": "2",
    "prev_page_url": null,
    "to": 2,
    "total": 1024
}

This endpoint retrieves all Tariffs.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/tariffs

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	product_id	int	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
product_id	int	10	No
tariff	varchar	100	No
tariff_description	varchar	100	Yes
data_amount	decimal	10,2	Yes
price	decimal	10,2	No
package	varchar	30	Yes
package_iphone	varchar	30	Yes
data_description	boolean		Yes
minimum_contract_length	boolean		No
bcad	varchar	30	Yes
spend_cap_available	boolean		Yes
5g_bolton_compatibility	boolean		Yes
legacy	boolean		No

Get All Tariffs For A Network

This command does not use any query parameters and returns all Tariffs for a Network as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/tariffs/{network}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "current_page": 1,
    "data": [
        {
            "product_id": 1,
            "tariff": "Q27QAA",
            "tariff_description": "Business Share 500 (new,24m)",
            "data_amount": "0.00",
            "price": "27.82",
            "package": "P5SAAS",
            "package_iphone": "P5SAAS",
            "data_description": null,
            "minimum_contract_length": 24,
            "bcad": null,
            "spend_cap_available": null,
            "5g_bolton_compatibility": null,
            "legacy": false
        },
        {
            "product_id": 2,
            "tariff": "Q27QAC",
            "tariff_description": "Business Share 1,300 (new,24m)",
            "data_amount": "0.00",
            "price": "50.09",
            "package": "P5SAAU",
            "package_iphone": "P5SAAU",
            "data_description": null,
            "minimum_contract_length": 24,
            "bcad": null,
            "spend_cap_available": null,
            "5g_bolton_compatibility": null,
            "legacy": false
        }
    ],
    "from": 1,
    "last_page": 512,
    "next_page_url": "https://alpha.propositionpro.com/l/api/v2/tariffs/{network}&page=2",
    "path": "https://alpha.propositionpro.com/l/api/v2/tariffs/{network}",
    "per_page": "2",
    "prev_page_url": null,
    "to": 2,
    "total": 1024
}

This endpoint retrieves all Tariffs for a Network.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/tariffs/{network}

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	product_id	int	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
product_id	int	10	No
tariff	varchar	30	No
tariff_description	varchar	100	Yes
data_amount	decimal	10,2	Yes
price	decimal	10,2	No
package	varchar	30	Yes
package_iphone	varchar	30	Yes
data_description	boolean		Yes
minimum_contract_length	boolean		No
bcad	varchar	30	Yes
spend_cap_available	boolean		Yes
5g_bolton_compatibility	boolean		Yes
legacy	boolean		No

Get All Boltons

This command does not use any query parameters and returns all Boltons as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/boltons" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "current_page": 1,
    "data": [
        {
            "dise_service_id": "P5SAAT",
            "dise_service_id_iphone": "P5SAAT",
            "dise_service_price": "16.68",
            "prop_description": "Business 500 Sharer [new] (24m)",
            "service_description": "Business 500 Sharer [new] (24m)",
            "mandatory": null,
            "sort_by": "Voice",
            "row_options": null,
            "5g_bolton": null,
            "legacy": false
        },
        {
            "dise_service_id": "P5SAAT",
            "dise_service_id_iphone": "P5SAAT",
            "dise_service_price": "16.68",
            "prop_description": "Business 500 Sharer [upgrade/re-sign] (24m)",
            "service_description": "Business 500 Sharer [upgrade/re-sign] (24m)",
            "mandatory": null,
            "sort_by": "Voice",
            "row_options": null,
            "5g_bolton": null,
            "legacy": false
        }
    ],
    "from": 1,
    "last_page": 12,
    "next_page_url": "https://alpha.propositionpro.com/l/api/v2/boltons&page=2",
    "path": "https://alpha.propositionpro.com/l/api/v2/boltons",
    "per_page": "2",
    "prev_page_url": null,
    "to": 2,
    "total": 24
}

This endpoint retrieves all Boltons.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/boltons

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	dise_service_id	string	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
dise_service_id	varchar	30	No
dise_service_id_iphone	varchar	30	No
dise_service_price	decimal	10,2	Yes
prop_description	varchar	100	Yes
service_description	varchar	100	No
mandatory	boolean		Yes
sort_by	varchar	100	Yes
row_options	boolean		Yes
5g_bolton	boolean		Yes
legacy	boolean		No

Get All Boltons For A Network

This command does not use any query parameters and returns all Boltons for a Network as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/boltons/{network}" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "current_page": 1,
    "data": [
        {
            "dise_service_id": "P5SAAT",
            "dise_service_id_iphone": "P5SAAT",
            "dise_service_price": "16.68",
            "prop_description": "Business 500 Sharer [new] (24m)",
            "service_description": "Business 500 Sharer [new] (24m)",
            "mandatory": null,
            "sort_by": "Voice",
            "row_options": null,
            "5g_bolton": null,
            "legacy": false
        },
        {
            "dise_service_id": "P5SAAT",
            "dise_service_id_iphone": "P5SAAT",
            "dise_service_price": "16.68",
            "prop_description": "Business 500 Sharer [upgrade/re-sign] (24m)",
            "service_description": "Business 500 Sharer [upgrade/re-sign] (24m)",
            "mandatory": null,
            "sort_by": "Voice",
            "row_options": null,
            "5g_bolton": null,
            "legacy": false
        }
    ],
    "from": 1,
    "last_page": 12,
    "next_page_url": "https://alpha.propositionpro.com/l/api/v2/boltons/{network}&page=2",
    "path": "https://alpha.propositionpro.com/l/api/v2/boltons/{network}",
    "per_page": "2",
    "prev_page_url": null,
    "to": 2,
    "total": 24
}

This endpoint retrieves all Boltons for a Network.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/boltons/{network}

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	dise_service_id	string	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
dise_service_id	varchar	30	No
dise_service_id_iphone	varchar	30	No
dise_service_price	decimal	10,2	Yes
prop_description	varchar	100	Yes
service_description	varchar	100	No
mandatory	boolean		Yes
sort_by	varchar	100	Yes
row_options	boolean		Yes
5g_bolton	boolean		Yes
legacy	boolean		No

Get All Boltons For A Tariff

This command does not use any query parameters and returns all Boltons for a Tariff as JSON:

curl "https://alpha.propositionpro.com/l/api/v2/tariffs/{product_id}/boltons" \
  -H "Authorization: Bearer PROPOSITION_API_KEY"

{
    "current_page": 1,
    "data": [
        {
            "dise_service_id": "P5SAAT",
            "dise_service_id_iphone": "P5SAAT",
            "dise_service_price": "16.68",
            "prop_description": "Business 500 Sharer [new] (24m)",
            "service_description": "Business 500 Sharer [new] (24m)",
            "mandatory": null,
            "sort_by": "Voice",
            "row_options": null,
            "5g_bolton": null,
            "legacy": false
        },
        {
            "dise_service_id": "P5SAAT",
            "dise_service_id_iphone": "P5SAAT",
            "dise_service_price": "16.68",
            "prop_description": "Business 500 Sharer [upgrade/re-sign] (24m)",
            "service_description": "Business 500 Sharer [upgrade/re-sign] (24m)",
            "mandatory": null,
            "sort_by": "Voice",
            "row_options": null,
            "5g_bolton": null,
            "legacy": false
        }
    ],
    "from": 1,
    "last_page": 12,
    "next_page_url": "https://alpha.propositionpro.com/l/api/v2/tariffs/{product_id}/boltons&page=2",
    "path": "https://alpha.propositionpro.com/l/api/v2/tariffs/{product_id}/boltons",
    "per_page": "2",
    "prev_page_url": null,
    "to": 2,
    "total": 24
}

This endpoint retrieves all Boltons for a Tariff.

HTTP Request

GET https://alpha.propositionpro.com/l/api/v2/tariffs/{product_id}/boltons

Query Parameters

Parameter	Default	Data Type	Description
per_page	50	integer	The number of results to return per page (Maximum 500).
sort_by	dise_service_id	string	If set, results will be ordered by the sort_by field.
sort_order	ASC	string	The order to sort results by (only when sort_by is used). Format is ASC or DESC.

Response Fields

Field	Data Type	Length	Nullable
dise_service_id	varchar	30	No
dise_service_id_iphone	varchar	30	No
dise_service_price	decimal	10,2	Yes
prop_description	varchar	100	Yes
service_description	varchar	100	No
mandatory	boolean		Yes
sort_by	varchar	100	Yes
row_options	boolean		Yes
5g_bolton	boolean		Yes
legacy	boolean		No

Mime Types

Valid Mime Types

Image formats

File Extension	Mime Type
jpg/jpeg/jpe	image/jpeg
gif	image/gif
png	image/png
bmp	image/bmp
tif/tiff	image/tiff
ico	image/x-icon

Video formats

File Extension	Mime Type
asf/asx/wax/wmv/wmx	video/asf
avi	video/avi
divx	video/divx
flv	video/x-flv
mov/qt	video/quicktime
mpeg/mpg/mpe	video/mpeg
mp4/m4v	video/mp4
ogv	video/ogg
mkv	video/x-matroska

Text formats

File Extension	Mime Type
txt/asc/c/cc/h	text/plain
csv	text/csv
tsv	text/tab-separated-values
ics	text/calendar
rtx	text/richtext
css	text/css
htm/html	text/html

Audio formats

File Extension	Mime Type
mp3/m4a/m4b	audio/mpeg
ra/ram	audio/x-realaudio
wav	audio/wav
ogg/oga	audio/ogg
mid/midi	audio/midi
wma	audio/wma
mka	audio/x-matroska

Misc application formats

File Extension	Mime Type
rtf	application/rtf
js	application/javascript
pdf	application/pdf
swf	application/x-shockwave-flash
class	application/java
tar	application/x-tar
zip	application/zip
gz/gzip	application/x-gzip
rar	application/rar
7z	application/x-7z-compressed

MS Office formats

File Extension	Mime Type
doc	application/msword
pot/pps/ppt	application/vnd.ms-powerpoint
wri	application/vnd.ms-write
xla/xls/xlt/xlw	application/vnd.ms-excel
mdb	application/vnd.ms-access
mpp	application/vnd.ms-project
docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
docm	application/vnd.ms-word.document.macroEnabled.12
dotx	application/vnd.openxmlformats-officedocument.wordprocessingml.template
dotm	application/vnd.ms-word.template.macroEnabled.12
xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
xlsm	application/vnd.ms-excel.sheet.macroEnabled.12
xlsb	application/vnd.ms-excel.sheet.binary.macroEnabled.12
xltx	application/vnd.openxmlformats-officedocument.spreadsheetml.template
xltm	application/vnd.ms-excel.template.macroEnabled.12
xlam	application/vnd.ms-excel.addin.macroEnabled.12
pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation
pptm	application/vnd.ms-powerpoint.presentation.macroEnabled.12
ppsx	application/vnd.openxmlformats-officedocument.presentationml.slideshow
ppsm	application/vnd.ms-powerpoint.slideshow.macroEnabled.12
potx	application/vnd.openxmlformats-officedocument.presentationml.template
potm	application/vnd.ms-powerpoint.template.macroEnabled.12
ppam	application/vnd.ms-powerpoint.addin.macroEnabled.12
sldx	application/vnd.openxmlformats-officedocument.presentationml.slide
sldm	application/vnd.ms-powerpoint.slide.macroEnabled.12
onetoc/onetoc2/onetmp/onepkg	application/onenote

OpenOffice formats

File Extension	Mime Type
odt	application/vnd.oasis.opendocument.text
odp	application/vnd.oasis.opendocument.presentation
ods	application/vnd.oasis.opendocument.spreadsheet
odg	application/vnd.oasis.opendocument.graphics
odc	application/vnd.oasis.opendocument.chart
odb	application/vnd.oasis.opendocument.database
odf	application/vnd.oasis.opendocument.formula

WordPerfect formats

File Extension	Mime Type
wp/wpd	application/wordperfect

Response Codes

The Proposition API uses the following response codes:

Successful Response Code	Meaning
200	Success.
201	Object created successfully.
204	No content. When an action was executed successfully, but there is no content to return.
207	Multiple statuses. When some requests were executed successfully, however some failed.

Error Response Code	Meaning
401	Unauthorized. The user needs to be authenticated.
403	Forbidden. The user is authenticated, but does not have the permissions to perform an action.
404	Not found.
422	Unprocessable Entity. Requests that fail to pass validation.
429	Too Many Requests.
500	Internal server error.
503	Service unavailable.