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.kyndryl.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.kyndryl.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

Generating the Access Token

Endpoint

Accept: application/json
Content-Type: application/json

POST /oauth

Parameters

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

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

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

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.

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

    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

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

Country Codes

US State Codes

Sample Code