Authentication
The Site Serve API uses OAuth 2.0 Authentication Protocol to allow access to the various methods. You need to use your access_token
with each API request. The access token is valid for 1 hour and needs to be refreshed. You can use the refresh_token
to regenerate a new access_token
.
The API is accessible at:
https://api.eightbarcollective.com
The sandbox is a virtual testing environment that mimics the production API methods. It provides a self-contained space where you can initiate and test your integrations to the SiteServe APIs without changing any live data. Its highly recommended that you start your integration using the sandbox and move to production once you have tested the integrations. The sandbox endpoint is available at:
https://api.sandbox.eightbarcollective.com
Generating the Authorization Token
The authorization token can be generate by a GET request to the below endpoint.
Endpoint
GET /oauth/authorize?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=/oauth/receivecode
&state=RANDOM_NUMBER
This will display an auth_code
on the screen. This authorization token can be then used to generate the access_token
and the refresh_token
. Please note that the access_token
is only valid of 1 hour.
Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
client_id |
string | required | Consumer Key provided to you when you signed up. |
redirect_uri |
string | required | The URL where you would be redirected after you have successfully authorized access. If you do not have access to a browser, you must set this to inapp . |
response_type |
string | required | Must be the string code . |
state |
string | required | Your client can insert state information that will be appended to the redirect_uri upon success user authorization. |
Generating the Access Token
Endpoint
Accept: application/json
Content-Type: application/json
POST /oauth
Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
client_id |
string | required | Consumer Key provided to you when you signed up. |
client_secret |
string | required | The Consumer Secret provided to you when you signed up. |
redirect_uri |
string | required | The URL where you would be redirected after you have successfully authorized access. If you do not have access to a browser, you must set this to inapp . If inapp is used as the redirect_uri , the access_token will never expire. |
code |
string | required | The authorization_token that you have received from the first step |
grant_type |
string | required | Must contain the string authorization_code grant type. |
Request Body
{
"redirect_uri":"/oauth/receivecode",
"client_id":"YOUR_CLIENT_ID",
"client_secret":"YOUR_ACCOUNT_PASSWORD",
"code":"AUTHORIZATION_TOKEN"",
"grant_type":"authorization_code"
}
Response Body
{
"access_token":"bf60c59ea896b46885de91307a3888bd6fe0259f",
"expires_in":3600,
"token_type":"Bearer",
"scope":null,
"refresh_token":"393b4061d46ed7b95004e60fc76601ed185b9a08"
}
Response Parameters
Parameter | Type | Description |
---|---|---|
access_token |
string | The access token generated by the system for your account. |
expires_in |
integer | The time in seconds for which the access token is valid. The default value is 3600 . |
token_type |
string | The type of the token generated. The default type is Bearer . |
scope |
string | The scope of access for the access_token |
refresh_token |
string | The refresh token that you can use to acquire a new access token after the current one expires. |
Refresh Tokens
Key points to consider when working with refresh tokens:
- Refresh tokens will not expire. They can only be invalidated explicitly by the user.
- As a best practice, you should always capture the refresh token after using it to get a new access token. It may change, and when it does you should use the new one.
- If you change your password, the existing refresh token should continue to work.
Refreshing the Access Token using the Refresh Token
You can use the refresh_token
to regenerate a new access_token
. As noted above
Endpoint
Accept: application/json
Content-Type: application/json
POST /oauth
Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
client_id |
string | required | Consumer Key provided to you when you signed up. |
client_secret |
string | required | The Consumer Secret provided to you when you signed up. |
grant_type |
string | required | Must contain the refresh_token grant type. |
refresh_token |
string | required | The refresh_token provided to you in the first step |
Request Body
{
"grant_type":"refresh_token",
"refresh_token":"393b4061d46ed7b95004e60fc76601ed185b9a08",
"client_id":"testclient",
"client_secret":"testpass"
}
Response Body
{
"access_token":"6d8db05ac28b38d29a1ec32f401753469ec35869",
"expires_in":3600,
"token_type":"Bearer",
"scope":null
}
Response Parameters
Parameter | Type | Description |
---|---|---|
access_token |
string | The access token generated by the system for your account. |
expires_in |
integer | The time in seconds for which the access token is valid. The default value is 3600 . |
token_type |
string | The type of the token generated. The default type is Bearer . |
scope |
string | The scope of access for the access_token |
Accessing the API
Uploading Leads
Leads can be imported by using the SiteServe Upload API. This API supports bulk operations.
Endpoint
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json
POST /siteserve/upload
Parameters
Please make sure that the 4 first fields described below are exactly matching the IO provided by the Agency Planning team, otherwise none of the rest of the data will be accepted.
Parameter | Type | Required? | Description |
---|---|---|---|
campaign_id |
string | required | The Campaign ID for which the lead was captured. Assigned by EightBar, cannot be changed. |
campaign_name |
string | required | The campaign name for which the lead was captured. Assigned by EightBar, cannot be changed. |
publisher_id |
string | required | The Publisher ID (Site Name/Code) for which the lead was captured. Assigned by EightBar, cannot be changed. |
placement_name |
string | required | The placement name for which the lead was captured. Assigned by EightBar, cannot be changed. |
source_site |
string | required | Web page or Agency Sourcing |
unique_order_number |
string | required | A Unique ID for each person registering defined by you, for each Campaign and Placement combination. Please note that this number has to be different than previously uploaded numbers (for the specific campaign/placement combination the lead is getting uploaded against), otherwise the lead information will not be accepted. |
title |
string | optional | Salutation of the lead. For example, Mr., Mr, Ms, Dr.. |
first_name |
string | required | First name of the lead |
middle_name |
string | optional | Middle name of the lead |
last_name |
string | required | Last name of the lead |
job_title |
string | required | Job title of the lead |
department |
string | optional | Department / Business Unit of the lead |
company |
string | required | Company with which the lead is associated with. |
company_size |
string | required | Size of the company |
address_line_1 |
string | required | Address Line 1 |
address_line_2 |
string | optional | Address Line 2 |
address_line_3 |
string | optional | Address Line 3 |
city |
string | required | City name of the lead |
state |
string | required if country is US, CA or CN | 2 digit state/province code of the lead. State information is only required for leads in US, Canada and China. Click here to see a list of all states and their codes. |
zip_code |
string | required | Zip code of the lead. For US, no dashes or periods just numbers. |
country |
string | required | Country code of the lead. Click here to see a list of all countries and their codes. |
phone |
string | required | Phone number of the lead. No dots, dashes or spaces, just numbers. |
extension |
string | optional | Honorific extension added to the name like Jr., Sr., etc. |
fax |
string | optional | FAX number of the lead |
email |
string | required | Email address of the lead |
ts_received |
string | optional | Time Stamp the lead was received by the system |
geography |
string | optional | Geographical classification of the lead's location |
ov_code |
string | required | OV Codes as confirmed by EightBar.(Can accept only alphanumeric values with max length 10) |
ww_score |
string | optional | World-wide Score |
custinfo1 |
string | optional | Custom Information about the lead |
custinfo2 |
string | optional | Custom Information about the lead |
privacy |
string | optional | Privacy setting opted by the lead |
tactic |
string | required | Tactic code of the placement |
response_type |
string | required | Response type. Allowed values can be: WEBRESP, REGSTRD or ATTND. |
asset_name |
string | optional | Asset name |
questionnum1_ooemail |
string | required | Allowed values can be Q_XSYS:OOEMAIL or Q_XSYS:OIEMAIL |
email_verification |
string | required | Status of the verification of the email address. Allowed values can be CHECKED or NOT CHECKED. |
questionnum2_ootele |
string | required | Allowed values can be Q_XSYS:OOTELE or Q_XSYS:OITELE |
phone_verification |
string | required | Status of the verification of the phone number. Allowed values can be CHECKED or NOT CHECKED. |
questionnum3_oopostal |
string | optional | Allowed values can be Q_XSYS:OOPOSTAL or Q_XSYS:OIPOSTAL |
zipcode_verification |
string | optional | Status of the verification of the zip code. Allowed values can be CHECKED or NOT CHECKED. |
timestamp |
string | required | Time Stamp the lead was received by your system. |
cn_pipl_consent |
boolean (true/false) | (required only for leads from China) | Consent provided by the registrant to share their personal information across borders. |
question_[n] |
string | optional | Optional question asked in the form. The [n] defines the number of the question. For example - question_1 , question_2 and so on. |
answer_[n] |
string | optional | Answers to the optional questions. Please note that the answers should have the same numbers are their questions. For example - question_1 should have answer_1 . |
offer_code |
string | required (For Unica 9.1) | The offer code provided by EightBar |
channel |
string | required (For Unica 9.1) | The channel from which the lead is generated. Valid values are Digital Inbound:Content Syndication, Event:Virtual or Event:Face to Face. |
interaction_type |
string | required (For Unica 9.1) | The type of interation the lead had. Allowed values can be ATTND, REGSTRD or CONTSYND. |
Request Body
A JSON array of one or more leads can be submitted using the POST method to this API.
[
{
"campaign_id":"163051",
"campaign_name":"2010 Q4|IBM_Non-CA_IT_Rational CS|NonIntel|NYC|USA",
"publisher_id":"I/EMEDIA (00104221)",
"placement_name":"AVIATION WEEK|Systems - Content Syndication|0x0",
"source_site":"TECHTARGET",
"unique_order_number":"23",
"title":"Mr",
"first_name":"John",
"middle_name":"E.",
"last_name":"Smith",
"job_title":"CEO",
"company":"Acne Corporation",
"company_size":"250 to 499",
"address_line_1":"address line 1",
"address_line_2":"address line 2",
"address_line_3":"address line 3",
"city":"New York City",
"state":"NY",
"zip_code":"10021",
"country":"US",
"phone":"9876543210",
"fax":"9876543211",
"email":"john.smith12@company.com",
"ts_received":"2015-03-01 23:13:19",
"extension":"Jr.",
"department":"department name",
"geography":"cgeography",
"ov_code":"OV124881",
"ww_score":"wwscore",
"custinfo1":"customer info 1",
"custinfo2":"customer info 2",
"privacy":"cprivacy",
"tactic":"C39103UX",
"response_type":"WEBRESP",
"asset_name":"assetname",
"questionnum1_ooemail":"Q_XSYS:OOEMAIL",
"email_verification":"CHECKED",
"questionnum2_ootele":"Q_XSYS:OOTELE",
"phone_verification":"CHECKED",
"questionnum3_oopostal":"Q_XSYS:OOPOSTAL",
"zipcode_verification":"NOT CHECKED",
"timestamp":"2014-03-21 11:38:52"
}
]
Response Body
The API will send a response to the calls in JSON format.
{
"response":{
"code": 200,
"request_id":"d65613aa069c45469f0b9e1b5efa1863",
"status":"Success",
"submitted_leads":1,
"uploaded_leads":1,
"duplicate_leads":0,
"invalid_leads":0
}
}
Response Parameters
Parameter | Type | Description |
---|---|---|
request_id |
string | The system generated ID for the submitted request which can be later used to get the status of the request. This is particularly useful in case of bulk lead imports. |
status |
string | The initial status of the request from the server. If the request was successful, it will return Success and if the request failed, it will return Failed. If you have submitted a large number of leads, the system may put it into batch processing. In that case, the status of the request would be returned as Pending. |
submitted_leads |
integer | The number of the leads submitted in the request. |
uploaded_leads |
integer | The number of leads successfully imported by the system. |
duplicate_leads |
integer | The number of duplicate leads in the request. A duplicate lead is defined as an email address already existing in the system for a particular campaign and placement. |
invalid_leads |
integer | The number of invalid leads submitted in the request. An invalid lead is classified as a lead with an invalid email address, incorrect placement/campaign mapping, invalid zip code and/or missing data for required fields. |
errors |
array (optional) | An array of error messages will ONLY appear if there are any duplicate or invalid leads. It will contain the reason for each of the duplicate and/or invalid leads. |
Assertion: submitted_leads = uploaded_leads + duplicate_leads + invalid_leads
Getting the Status of a Request
If you have submitted multiple leads and the initial status in the response is pending
, you can use the SiteServe Status API to get the updated status at any time. As a best practice, you should store the request IDs generated by the system for the requests made by your application.
Endpoint
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json
GET /siteserve/status[/:request_id]
Request Parameters
Parameter | Type | Required? | Description |
---|---|---|---|
request_id | string | optional | The request_id for which you want to fetch the status. If no request_id is passed, the API will return the current status of the last 25 requests. |
Response Body
{
"request_id":"d65613aa069c45469f0b9e1b5efa1863",
"created_date":"2015-03-26T04:11:40+05:30",
"response":{
"status": "Success",
"submitted_leads": 10,
"uploaded_leads": 8,
"duplicate_leads": 1,
"invalid_leads": 1,
"errors": {
"Record with EmailAddress='alice@example.com', CampaignID='1234567890111112', PlacementName='placement name' was found duplicate.",
"Record with EmailAddress='bob@example', CampaignID='1234567890112', PlacementName='placement name' have invalid emailAddress."
"Record with EmailAddress='winston@example.com', CampaignID='1234567890112', PlacementName='placement name' have invalid tactic code."
}
}
}
Response Parameters
Parameter | Type | Description |
---|---|---|
request_id |
string | The system generated ID for the request which can be later used to get the status of the request. This is particularly useful in case of bulk lead imports. |
created_date |
datetime | The timestamp of the request in ISO 8601 format. |
status |
string | The current status of the request from the server. If the request was successful, it will return Success and if the request failed, it will return Failed. |
submitted_leads |
integer | The number of the leads submitted in the request. |
uploaded_leads |
integer | The number of leads successfully imported by the system. |
duplicate_leads |
integer | The number of duplicate leads in the request. A duplicate lead is defined as an email address already existing in the system for a particular campaign and placement. |
invalid_leads |
integer | The number of invalid leads submitted in the request. An invalid lead is classified as a lead with an invalid email address, incorrect placement/campaign mapping, invalid zip code. |
errors |
array (optional) | An array of error messages will ONLY appear if there are any duplicate or invalid leads. It will contain the reason for each of the duplicate and/or invalid leads. |
Country Codes
Please find the list of ISO 3166-1 Country Codes below:Country Name | Country Code | ||
---|---|---|---|
Australia | AU | Austria | AT |
Azerbaijan | AZ | Bahamas | BS |
Bahrain | BH | Bangladesh | BD |
Barbados | BB | Belarus | BY |
Belgium | BE | Belize | BZ |
Benin | BJ | Bermuda | BM |
Bhutan | BT | Bolivia | BO |
Bosnia and Herzegovina | BA | Botswana | BW |
Bouvet Island | BV | Brazil | BR |
British Indian Ocean Territory | IO | Brunei Darussalam | BN |
Bulgaria | BG | Burkina Faso | BF |
Burundi | BI | Cambodia | KH |
Cameroon | CM | Cape Verde | CV |
Caribbean Netherlands | BQ | Cayman Islands | KY |
Central African Republic | CF | Chad | TD |
Chile | CL | China | CN |
Christmas Island | CX | Cocos (Keeling) Islands | CC |
Colombia | CO | Comoros | KM |
Congo | CG | Democratic Republic of Congo | CD |
Cook Islands | CK | Costa Rica | CR |
Câ„¢te d'Ivoire | CI | Croatia | HR |
Cuba | CU | Cura<8d>ao | CW |
Cyprus | CY | Czech Republic | CZ |
Denmark | DK | Djibouti | DJ |
Dominica | DM | Dominican Republic | DO |
Ecuador | EC | Egypt | EG |
El Salvador | SV | Equatorial Guinea | GQ |
Eritrea | ER | Estonia | EE |
Ethiopia | ET | Falkland Islands | FK |
Faroe Islands | FO | Fiji | FJ |
Finland | FI | France | FR |
French Guiana | GF | French Polynesia | PF |
French Southern Territories | TF | Gabon | GA |
Gambia | GM | Georgia | GE |
Germany | DE | Ghana | GH |
Gibraltar | GI | Greece | GR |
Greenland | GL | Grenada | GD |
Guadeloupe | GP | Guam | GU |
Guatemala | GT | Guernsey | GG |
Guinea | GN | Guinea-Bissau | GW |
Guyana | GY | Haiti | HT |
Heard and McDonald Islands | HM | Honduras | HN |
Hong Kong | HK | Hungary | HU |
Iceland | IS | India | IN |
Indonesia | ID | Iran | IR |
Iraq | IQ | Ireland | IE |
Isle of Man | IM | Israel | IL |
Italy | IT | Jamaica | JM |
Japan | JP | Jersey | JE |
Jordan | JO | Kazakhstan | KZ |
Kenya | KE | Kiribati | KI |
Kuwait | KW | Kyrgyzstan | KG |
Lao People's Democratic Republic | LA | Latvia | LV |
Lebanon | LB | Lesotho | LS |
Liberia | LR | Libya | LY |
Liechtenstein | LI | Lithuania | LT |
Luxembourg | LU | Macau | MO |
Macedonia | MK | Madagascar | MG |
Malawi | MW | Malaysia | MY |
Maldives | MV | Mali | ML |
Malta | MT | Marshall Islands | MH |
Martinique | MQ | Mauritania | MR |
Mauritius | MU | Mayotte | YT |
Mexico | MX | Micronesia, Federated States of Micronesia | FM |
Moldova | MD | Monaco | MC |
Mongolia | MN | Montenegro | ME |
Montserrat | MS | Morocco | MA |
Mozambique | MZ | Myanmar | MM |
Namibia | NA | Nauru | NR |
Nepal | NP | New Caledonia | NC |
New Zealand | NZ | Nicaragua | NI |
Niger | NE | Nigeria | NG |
Niue | NU | Norfolk Island | NF |
North Korea | KP | Northern Mariana Islands | MP |
Norway | NO | Oman | OM |
Pakistan | PK | Palau | PW |
State of Palestine | PS | Panama | PA |
Papua New Guinea | PG | Paraguay | PY |
Peru | PE | Philippines | PH |
Pitcairn | PN | Poland | PL |
Portugal | PT | Puerto Rico | PR |
Qatar | QA | RŽunion | RE |
Romania | RO | Russian Federation | RU |
Rwanda | RW | Saint Barthelemy | BL |
Saint Helena | SH | Saint Kitts and Nevis | KN |
Saint Lucia | LC | Saint Vincent and the Grenadines | VC |
Saint-Martin (France) | MF | Samoa | WS |
San Marino | SM | Sao Tome and Principe | ST |
Saudi Arabia | SA | Senegal | SN |
Serbia | RS | Seychelles | SC |
Sierra Leone | SL | Singapore | SG |
Sint Maarten (Dutch part) | SX | Slovakia | SK |
Slovenia | SI | Solomon Islands | SB |
Somalia | SO | South Africa | ZA |
South Georgia and the South Sandwich Islands | GS | South Korea | KR |
South Sudan | SS | Spain | ES |
Sri Lanka | LK | St. Pierre and Miquelon | PM |
Sudan | SD | Suriname | SR |
Svalbard and Jan Mayen Islands | SJ | Swaziland | SZ |
Sweden | SE | Switzerland | CH |
Syria | SY | Taiwan | TW |
Tajikistan | TJ | Tanzania | TZ |
Thailand | TH | The Netherlands | NL |
Timor-Leste | TL | Togo | TG |
Tokelau | TK | Tonga | TO |
Trinidad and Tobago | TT | Tunisia | TN |
Turkey | TR | Turkmenistan | TM |
Turks and Caicos Islands | TC | Tuvalu | TV |
Uganda | UG | Ukraine | UA |
United Arab Emirates | AE | United Kingdom | GB |
United States | US | United States Minor Outlying Islands | UM |
Uruguay | UY | Uzbekistan | UZ |
Vanuatu | VU | Vatican | VA |
Venezuela | VE | Vietnam | VN |
Virgin Islands (British) | VG | Virgin Islands (U.S.) | VI |
Wallis and Futuna Islands | WF | Western Sahara | EH |
Yemen | YE | Zambia | ZM |
Zimbabwe | ZW |
US State Codes
Please find the list of US States and their Codes below:State Name | State Code | State Name | State Code | State Name | State Code | State Name | State Code |
---|---|---|---|---|---|---|---|
Alabama | AL | Alaska | AK | Arizona | AZ | Arkansas | AR |
California | CA | Colorado | CO | Connecticut | CT | Delaware | DE |
District of Columbia | DC | Florida | FL | Georgia | GA | Hawaii | HI |
Idaho | ID | Illinois | IL | Indiana | IN | Iowa | IA |
Kansas | KS | Kentucky | KY | Louisiana | LA | Maine | ME |
Montana | MT | Nebraska | NE | Nevada | NV | New Hampshire | NH |
New Jersey | NJ | New Mexico | NM | New York | NY | North Carolina | NC |
North Dakota | ND | Ohio | OH | Oklahoma | OK | Oregon | OR |
Maryland | MD | Massachusetts | MA | Michigan | MI | Minnesota | MN |
Mississippi | MS | Missouri | MO | Pennsylvania | PA | Rhode Island | RI |
South Carolina | SC | South Dakota | SD | Tennessee | TN | Texas | TX |
Utah | UT | Vermont | VT | Virginia | VA | Washington | WA |
West Virginia | WV | Wisconsin | WI | Wyoming | WY |
Sample Code
Sample code is available in selected languages to help you write integrations faster. Below is a list of all sample codes available in various programming languages:Language | File Name | Link |
---|---|---|
C# | SiteServeCSharpSample.zip | Download |
Java | SiteServeJavaSample.zip | Download |
PHP | SiteServePhpSample.zip | Download |
Python | SiteServePythonSample.zip | Download |