Partner API Guide • Version 1.20 • Prepared by John Jackson • 10 October 2017
Introduction
This API allows the creation, reading, updating or deletion of partners. The request is made by making an HTTP POST of an XML message containing an access key, request type and other elements.
The Request
To use this API, an access key is required. Provide the key in a key element within the request. Access keys can be created in ‘Settings > Access Keys’.
For each request, a request element must also be given containing either create read update delete. Details of how to make each request type are given below.
If the main service is accessed at the address domain.example.com, then a POST request should be made to the corresponding API URL:
https://domain.example.com/api/APIPartner.php
An XML message should be sent as the POST data:
<?xml version="1.0" encoding="ISO-8859-1"?> <data> <key>Yrg32FoiRdSriLYEbLrzSvFmurBGsPiz</key> <request>create</request> ... </data>
The Response
The server will respond with XML data. The response will always contain Code (error code) and Message (response message) elements. If there are several messages, there may be multiple Message elements. If successful, other response elements will also be returned.
A successful response may look like this:
<?xml version="1.0" encoding="ISO-8859-1"?> <result> <code>0</code> <message>OK</message> ... </result>
Create
<request>create</request>
Parameters
If parameters other than the required ones are not supplied, default values will be used. Parameters marked Conditional become required only when another related field is supplied.
| Parameter | Required | Description |
|---|---|---|
| Partner details | ||
| siteid | Optional | The default site ID to use for this partner. |
| company | Required | Partner’s company name. |
| description | Optional | Additional description for partner. |
| reference | Optional | Internal reference code/number for this partner. |
| customerphone | Optional | Customer enquiry phone number. |
| customeremail | Optional | Customer enquiry email address. |
| customeropeninghours | Optional | Customer opening hours. |
| title | Conditional | Partner’s title — Mr. Mrs. Ms. Miss Dr. Rev.. Required if other parts of the name are supplied. |
| firstname | Conditional | Partner’s first name. Required if other parts of the name are supplied. |
| lastname | Conditional | Partner’s last name. Required if other parts of the name are supplied. |
| phone | Optional | Phone number. |
| transferphone | Optional | Phone number for transferring leads. |
| mobile | Optional | Mobile phone number. |
| fax | Optional | Fax number. |
| Optional | Email address. | |
| address | Optional | Address line 1. |
| address2 | Optional | Address line 2. |
| address3 | Optional | Address line 3. |
| towncity | Optional | Town or city. |
| postcode | Optional | Postcode. |
| fsanumber | Optional | FSA authorisation number. |
| notes | Optional | Notes. |
| password | Optional | Password. |
| passwordconfirm | Optional | Password confirmation (must match password). |
| Email delivery | ||
| emaildeliveryenabled | Optional | Email delivery enabled — Yes No. |
| emaildeliveryaddress | Optional | Email delivery email address(es). Comma separate multiple addresses. |
| emaildeliverycustom | Optional | Use custom template for email delivery — Yes No. |
| emaildeliverysubject | Optional | Custom email delivery template subject line. |
| emaildeliverytemplate | Optional | Custom email delivery template body. |
| emailfollowupsubject | Optional | Custom email follow-up template subject line. |
| emailfollowuptemplate | Optional | Custom email follow-up template body. |
| Internet delivery | ||
| internetdeliveryenabled | Optional | Internet delivery enabled — Yes No. |
| internetdeliveryrequestmethod | Optional | Internet delivery request method — post get. |
| internetdeliverycontenttype | Optional | Internet delivery content type — xml form. |
| internetdeliveryurl | Optional | Internet delivery URL. |
| internetdeliverytemplate | Optional | Internet delivery template. |
| internetfollowupurl | Optional | Internet delivery follow-up URL. |
| internetfollowuptemplate | Optional | Internet delivery follow-up template. |
| internetdeliverytagresultdescription | Optional | Internet delivery result description XML element. |
| internetdeliverytagresultref | Optional | Internet delivery return reference XML element. |
| Delivery schedule | ||
| deliveryschedule | Optional | Delivery schedule enabled — Yes No. |
| deliveryscheduleday1 | Optional | Deliver on Mondays — Yes No. |
| deliveryscheduleday1start | Optional | Monday delivery start time. e.g. 09:00. |
| deliveryscheduleday1end | Optional | Monday delivery end time. e.g. 17:00. |
| deliveryscheduleday2 | Optional | Deliver on Tuesdays — Yes No. |
| deliveryscheduleday2start | Optional | Tuesday delivery start time. e.g. 09:00. |
| deliveryscheduleday2end | Optional | Tuesday delivery end time. e.g. 17:00. |
| deliveryscheduleday3 | Optional | Deliver on Wednesdays — Yes No. |
| deliveryscheduleday3start | Optional | Wednesday delivery start time. e.g. 09:00. |
| deliveryscheduleday3end | Optional | Wednesday delivery end time. e.g. 17:00. |
| deliveryscheduleday4 | Optional | Deliver on Thursdays — Yes No. |
| deliveryscheduleday4start | Optional | Thursday delivery start time. e.g. 09:00. |
| deliveryscheduleday4end | Optional | Thursday delivery end time. e.g. 17:00. |
| deliveryscheduleday5 | Optional | Deliver on Fridays — Yes No. |
| deliveryscheduleday5start | Optional | Friday delivery start time. e.g. 09:00. |
| deliveryscheduleday5end | Optional | Friday delivery end time. e.g. 17:00. |
| deliveryscheduleday6 | Optional | Deliver on Saturdays — Yes No. |
| deliveryscheduleday6start | Optional | Saturday delivery start time. e.g. 09:00. |
| deliveryscheduleday6end | Optional | Saturday delivery end time. e.g. 17:00. |
| deliveryscheduleday7 | Optional | Deliver on Sundays — Yes No. |
| deliveryscheduleday7start | Optional | Sunday delivery start time. e.g. 09:00. |
| deliveryscheduleday7end | Optional | Sunday delivery end time. e.g. 17:00. |
| Limits | ||
| creditlimit | Optional | Credit limit. |
| dailylimit | Optional | Daily lead delivery limit. |
| monthlylimit | Optional | Monthly lead delivery limit. |
| Alerts and settings | ||
| leadtextalerts | Optional | Enable text message alerts on being referred a lead — Yes No. |
| fundstextalerts | Optional | Enable text message alerts when funds are running low — Yes No. |
| fundsthreshold | Optional | Low funds threshold. |
| referralpartner | Optional | Leads will be referred to partner — Yes No. |
| introducer | Optional | Leads will be introduced by partner — Yes No. |
| accesslevel | Optional | Portal access level — Standard SearchOnly SearchExcluded. |
| manuallyacceptleads | Optional | Require leads to be manually accepted after referral — Yes No. |
| updatestatus | Optional | Allow referral partners to update the status of leads — Yes No. |
| online | Optional | Online status — Online Offline. |
| sendemail | Optional | Send a welcome email to the new partner — Yes No. |
Response
| Field | Description |
|---|---|
| id | The ID of the new partner. |
Error Codes
| Code | Description |
|---|---|
| 0 | No errors |
| 1 | Validation or authentication error |
| 2 | XML format error or no XML provided |
| 3 | The email address is already allocated to another account |
| 4 | The account’s user limit has been reached |
Read
<request>read</request>
Parameters
| Parameter | Required | Description |
|---|---|---|
| id | Required | The ID of the partner to read. |
Response
| Field | Description |
|---|---|
| id | The ID of the partner. |
| Partner details | |
| siteid | The default site ID to use for this partner. |
| company | Partner’s company name. |
| description | Additional description for partner. |
| reference | Internal reference code/number for this partner. |
| customerphone | Customer enquiry phone number. |
| customeremail | Customer enquiry email address. |
| customeropeninghours | Customer opening hours. |
| title | Partner’s title — Mr. Mrs. Ms. Miss Dr. Rev.. Required if other parts of the name are supplied. |
| firstname | Partner’s first name. Required if other parts of the name are supplied. |
| lastname | Partner’s last name. Required if other parts of the name are supplied. |
| phone | Phone number. |
| transferphone | Phone number for transferring leads. |
| mobile | Mobile phone number. |
| fax | Fax number. |
| Email address. | |
| address | Address line 1. |
| address2 | Address line 2. |
| address3 | Address line 3. |
| towncity | Town or city. |
| postcode | Postcode. |
| fsanumber | FSA authorisation number. |
| notes | Notes. |
| Email delivery | |
| emaildeliveryenabled | Email delivery enabled — Yes No. |
| emaildeliveryaddress | Email delivery email address(es). Comma separate multiple addresses. |
| emaildeliverycustom | Use custom template for email delivery — Yes No. |
| emaildeliverysubject | Custom email delivery template subject line. |
| emaildeliverytemplate | Custom email delivery template body. |
| emailfollowupsubject | Custom email follow-up template subject line. |
| emailfollowuptemplate | Custom email follow-up template body. |
| Internet delivery | |
| internetdeliveryenabled | Internet delivery enabled — Yes No. |
| internetdeliveryrequestmethod | Internet delivery request method — post get. |
| internetdeliverycontenttype | Internet delivery content type — xml form. |
| internetdeliveryurl | Internet delivery URL. |
| internetdeliverytemplate | Internet delivery template. |
| internetfollowupurl | Internet delivery follow-up URL. |
| internetfollowuptemplate | Internet delivery follow-up template. |
| internetdeliverytagresultdescription | Internet delivery result description XML element. |
| internetdeliverytagresultref | Internet delivery return reference XML element. |
| Delivery schedule | |
| deliveryschedule | Delivery schedule enabled — Yes No. |
| deliveryscheduleday1 | Deliver on Mondays — Yes No. |
| deliveryscheduleday1start | Monday delivery start time. e.g. 09:00. |
| deliveryscheduleday1end | Monday delivery end time. e.g. 17:00. |
| deliveryscheduleday2 | Deliver on Tuesdays — Yes No. |
| deliveryscheduleday2start | Tuesday delivery start time. e.g. 09:00. |
| deliveryscheduleday2end | Tuesday delivery end time. e.g. 17:00. |
| deliveryscheduleday3 | Deliver on Wednesdays — Yes No. |
| deliveryscheduleday3start | Wednesday delivery start time. e.g. 09:00. |
| deliveryscheduleday3end | Wednesday delivery end time. e.g. 17:00. |
| deliveryscheduleday4 | Deliver on Thursdays — Yes No. |
| deliveryscheduleday4start | Thursday delivery start time. e.g. 09:00. |
| deliveryscheduleday4end | Thursday delivery end time. e.g. 17:00. |
| deliveryscheduleday5 | Deliver on Fridays — Yes No. |
| deliveryscheduleday5start | Friday delivery start time. e.g. 09:00. |
| deliveryscheduleday5end | Friday delivery end time. e.g. 17:00. |
| deliveryscheduleday6 | Deliver on Saturdays — Yes No. |
| deliveryscheduleday6start | Saturday delivery start time. e.g. 09:00. |
| deliveryscheduleday6end | Saturday delivery end time. e.g. 17:00. |
| deliveryscheduleday7 | Deliver on Sundays — Yes No. |
| deliveryscheduleday7start | Sunday delivery start time. e.g. 09:00. |
| deliveryscheduleday7end | Sunday delivery end time. e.g. 17:00. |
| Balances and totals | |
| balance | Current balance. |
| creditlimit | Credit limit. |
| dailylimit | Daily lead delivery limit. |
| monthlylimit | Monthly lead delivery limit. |
| deliveredtoday | Number of leads delivered today. |
| deliveredthismonth | Number of leads delivered this month. |
| deliveredlastmonth | Number of leads delivered last month. |
| averagetoday | Average amount paid per lead today. |
| averagethismonth | Average amount paid per lead this month. |
| averagelastmonth | Average amount paid per lead last month. |
| Alerts and settings | |
| leadtextalerts | Enable text message alerts on being referred a lead — Yes No. |
| fundstextalerts | Enable text message alerts when funds are running low — Yes No. |
| fundsthreshold | Low funds threshold. |
| referralpartner | Leads will be referred to partner — Yes No. |
| introducer | Leads will be introduced by partner — Yes No. |
| accesslevel | Portal access level — Standard SearchOnly SearchExcluded. |
| manuallyacceptleads | Require leads to be manually accepted after referral — Yes No. |
| updatestatus | Allow referral partners to update the status of leads — Yes No. |
| active | Partner status — Active Pending Inactive. |
| online | Online status — Online Offline. |
| created | The date and time that the partner was created. e.g. 2011-01-01 12:00:00. |
Error Codes
| Code | Description |
|---|---|
| 0 | No errors |
| 1 | Validation or authentication error |
| 2 | XML format error or no XML provided |
Update
<request>update</request>
Parameters
Any parameter not supplied is left unchanged.
| Parameter | Required | Description |
|---|---|---|
| id | Required | The ID of the partner to update. |
| Partner details | ||
| siteid | Optional | The default site ID to use for this partner. |
| company | Required | Partner’s company name. |
| description | Optional | Additional description for partner. |
| reference | Optional | Internal reference code/number for this partner. |
| customerphone | Optional | Customer enquiry phone number. |
| customeremail | Optional | Customer enquiry email address. |
| customeropeninghours | Optional | Customer opening hours. |
| title | Conditional | Partner’s title — Mr. Mrs. Ms. Miss Dr. Rev.. Required if other parts of the name are supplied. |
| firstname | Conditional | Partner’s first name. Required if other parts of the name are supplied. |
| lastname | Conditional | Partner’s last name. Required if other parts of the name are supplied. |
| phone | Optional | Phone number. |
| transferphone | Optional | Phone number for transferring leads. |
| mobile | Optional | Mobile phone number. |
| fax | Optional | Fax number. |
| Optional | Email address. | |
| address | Optional | Address line 1. |
| address2 | Optional | Address line 2. |
| address3 | Optional | Address line 3. |
| towncity | Optional | Town or city. |
| postcode | Optional | Postcode. |
| fsanumber | Optional | FSA authorisation number. |
| notes | Optional | Notes. |
| password | Optional | Password. |
| passwordconfirm | Optional | Password confirmation (must match password). |
| Email delivery | ||
| emaildeliveryenabled | Optional | Email delivery enabled — Yes No. |
| emaildeliveryaddress | Optional | Email delivery email address(es). Comma separate multiple addresses. |
| emaildeliverycustom | Optional | Use custom template for email delivery — Yes No. |
| emaildeliverysubject | Optional | Custom email delivery template subject line. |
| emaildeliverytemplate | Optional | Custom email delivery template body. |
| emailfollowupsubject | Optional | Custom email follow-up template subject line. |
| emailfollowuptemplate | Optional | Custom email follow-up template body. |
| Internet delivery | ||
| internetdeliveryenabled | Optional | Internet delivery enabled — Yes No. |
| internetdeliveryrequestmethod | Optional | Internet delivery request method — post get. |
| internetdeliverycontenttype | Optional | Internet delivery content type — xml form. |
| internetdeliveryurl | Optional | Internet delivery URL. |
| internetdeliverytemplate | Optional | Internet delivery template. |
| internetfollowupurl | Optional | Internet delivery follow-up URL. |
| internetfollowuptemplate | Optional | Internet delivery follow-up template. |
| internetdeliverytagresultdescription | Optional | Internet delivery result description XML element. |
| internetdeliverytagresultref | Optional | Internet delivery return reference XML element. |
| Delivery schedule | ||
| deliveryschedule | Optional | Delivery schedule enabled — Yes No. |
| deliveryscheduleday1 | Optional | Deliver on Mondays — Yes No. |
| deliveryscheduleday1start | Optional | Monday delivery start time. e.g. 09:00. |
| deliveryscheduleday1end | Optional | Monday delivery end time. e.g. 17:00. |
| deliveryscheduleday2 | Optional | Deliver on Tuesdays — Yes No. |
| deliveryscheduleday2start | Optional | Tuesday delivery start time. e.g. 09:00. |
| deliveryscheduleday2end | Optional | Tuesday delivery end time. e.g. 17:00. |
| deliveryscheduleday3 | Optional | Deliver on Wednesdays — Yes No. |
| deliveryscheduleday3start | Optional | Wednesday delivery start time. e.g. 09:00. |
| deliveryscheduleday3end | Optional | Wednesday delivery end time. e.g. 17:00. |
| deliveryscheduleday4 | Optional | Deliver on Thursdays — Yes No. |
| deliveryscheduleday4start | Optional | Thursday delivery start time. e.g. 09:00. |
| deliveryscheduleday4end | Optional | Thursday delivery end time. e.g. 17:00. |
| deliveryscheduleday5 | Optional | Deliver on Fridays — Yes No. |
| deliveryscheduleday5start | Optional | Friday delivery start time. e.g. 09:00. |
| deliveryscheduleday5end | Optional | Friday delivery end time. e.g. 17:00. |
| deliveryscheduleday6 | Optional | Deliver on Saturdays — Yes No. |
| deliveryscheduleday6start | Optional | Saturday delivery start time. e.g. 09:00. |
| deliveryscheduleday6end | Optional | Saturday delivery end time. e.g. 17:00. |
| deliveryscheduleday7 | Optional | Deliver on Sundays — Yes No. |
| deliveryscheduleday7start | Optional | Sunday delivery start time. e.g. 09:00. |
| deliveryscheduleday7end | Optional | Sunday delivery end time. e.g. 17:00. |
| Limits | ||
| creditlimit | Optional | Credit limit. |
| dailylimit | Optional | Daily lead delivery limit. |
| monthlylimit | Optional | Monthly lead delivery limit. |
| Alerts and settings | ||
| leadtextalerts | Optional | Enable text message alerts on being referred a lead — Yes No. |
| fundstextalerts | Optional | Enable text message alerts when funds are running low — Yes No. |
| fundsthreshold | Optional | Low funds threshold. |
| referralpartner | Optional | Leads will be referred to partner — Yes No. |
| introducer | Optional | Leads will be introduced by partner — Yes No. |
| accesslevel | Optional | Portal access level — Standard SearchOnly SearchExcluded. |
| manuallyacceptleads | Optional | Require leads to be manually accepted after referral — Yes No. |
| updatestatus | Optional | Allow referral partners to update the status of leads — Yes No. |
| active | Optional | Partner status — Active Pending Inactive. |
| online | Optional | Online status — Online Offline. |
Response
| Field | Description |
|---|---|
| id | The ID of the partner. |
Error Codes
| Code | Description |
|---|---|
| 0 | No errors |
| 1 | Validation or authentication error |
| 2 | XML format error or no XML provided |
| 3 | The email address is already allocated to another account |
| 4 | The account’s user limit has been reached |
Delete
<request>delete</request>
Parameters
| Parameter | Required | Description |
|---|---|---|
| id | Required | The ID of the partner to delete. |
Response
| Field | Description |
|---|---|
| id | The ID of the partner. |
Error Codes
| Code | Description |
|---|---|
| 0 | No errors |
| 1 | Validation or authentication error |
| 2 | XML format error or no XML provided |
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article