Resource Center

Search

API Overview

Welcome to the Pepperjam API documentation section! Our API is accessible through a REST-based interface. Listed below are some of the syntax conventions used in the documentation, general URI structure information, response formats, response codes, and HTTP methods used throughout the API.

 

API Overview

 

Syntax Conventions

 

Notation Meaning Example
Curly Brackets { } Required Item https://api.pepperjamnetwork.com/{resource}
 
In this example, resource is required.
Square Brackets [ ] Optional Item https://api.pepperjamnetwork.com[?param1=param]
 
In this example, the request parameter 'param1' is optional.
Less Than / Greater Than <> Placeholder Item { "data" : "<placeholder_data>" }
 
In this example, the request parameter 'placeholder_data' is a placeholder for larger data

 

URL Structure

Pepperjam API requests start with https://api.pepperjamnetwork.com.  An example of a complete and well-formed request is shown below:

https://api.pepperjamnetwork.com/{version}/{resource}?apiKey={apiKey}&format={format}

 

Request Parameters

All query string parameters should be camel-cased (eg. firstName, programId, apiKey) 

Parameter Description Possible Values Default Required
version This is the version of the API Key. N/A N/A Yes
resource The resource you're trying to access. N/A N/A Yes
apiKey Your API Key N/A N/A Yes
format The format the response will be returned in. json or xml N/A Yes
page The page the client is requesting. Used for resources that support pagination. * Any page in the range of total pages 1 No
 



* Values shown are placeholder values. Please replace with actual data.


Response Format

All return parameters will be snake-cased (eg. first_name, program_id, start_date)

The API returns 2 types of responses (JSON, XML).

JSON and XML responses will be paginated with a limit of 2500 results per request.

  • JSON-encoded objects (content-type: application/json).
GET
{
"meta" : {
    "status" : {     
        "code" : 200,
        "message" : "OK"
    },
    "pagination" : {     
        "total_results" : 1000,
        "total_pages" : 2,
        "next" : {  // Only available if there's a next page
            "rel" : "next",
            "href" : "<next_page_link>",
            "description" : "Next Page"
        },
        "previous" : {  // Only available if there's a previous page 
            "rel" : "previous",
            "href" : "<previous_page_link>",
            "description" : "Previous Page"
        }
    },
    "requests" : {     
        "current" : <current_requests>,
        "maximum" : <maximum_requests_per_day>
    },
},
"data" : { ... } // Can be an array [] or an object {}
}
POST
{
"meta" : {
    "status" : {     
        "code" : 201,
        "message" : "(Created resource message)"
    },
    "location" : {     
        "rel" : "created_resource",
        "href" : "https://api.pepperjamnetwork.com/{version}/{resource}?apiKey={apiKey}&format={format}&id={resourceId}",
        "description" : "Location of created resource"
    },
    "requests" : {     
        "current" : <current_requests>,
        "maximum" : <maximum_requests_per_day>
    },
},
"data" : []
}
PUT
{
"meta" : {
    "status" : {     
        "code" : 200,
        "message" : "(Updated resource message)"
    },
    "requests" : {     
        "current" : <current_requests>,
        "maximum" : <maximum_requests_per_day>
    },
},
"data" : []
}
DELETE
{
"meta" : {
    "status" : {     
        "code" : 204,
        "message" : "(Deleted resource message)"
    },
    "requests" : {     
        "current" : <current_requests>,
        "maximum" : <maximum_requests_per_day>
    },
},
"data" : []
}
  • XML (content-type: text/xml)
GET
<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
    <meta>
        <status>
            <code>200</code>
            <message>OK</message>
        </status>
        <pagination>
            <total_results>1000</total_results>
            <total_pages>2</total_pages>
            <next> <!-- Only available if there's a next page -->
                <rel>next</rel>
                <href><next_page_link></href>
                <description>Next Page</description>
            </next>
            <previous> <!-- Only available if there's a next page -->
                <rel>previous</rel>
                <href><previous_page_link></href>
                <description>Previous Page</description>
            </previous>
        </pagination>
        <requests>
            <current><current_requests></current>
            <maximum><maximum_requests_per_day></maximum>
        </requests>
    </meta>
    <data><!-- Can be an array [] or an object {} -->
        <program_name>My Program</program_name>
        <date>2012-01-01</date>
        ...       
    </data>
    <data>      
        <program_name>My Program</program_name>
        <date>2012-01-01</date>
        ...       
    </data>
</response>
POST
<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
    <meta>
        <status>
            <code>201</code>
            <message>(Created resource message)</message>
        </status>
        <location>
            <rel>created_resource</rel>
            <href>https://api.pepperjamnetwork.com/{version}/{resource}?apiKey={apiKey}&format={format}&id={resourceId}</href>
            <description>Location of created resource</description>
        </location>
        <requests>
            <current><current_requests></current>
            <maximum><maximum_requests_per_day></maximum>
        </requests>
    </meta>
    <data/>
</response>
PUT
<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
    <meta>
        <status>
            <code>200</code>
            <message>(Updated resource message)</message>
        </status>
        <requests>
            <current><current_requests></current>
            <maximum><maximum_requests_per_day></maximum>
        </requests>
    </meta>
    <data/>
</response>
DELETE
<?xml version="1.0" encoding="ISO-8859-1"?>
<response>
    <meta>
        <status>
            <code>204</code>
            <message>(Deleted resource message)</message>
        </status>
        <requests>
            <current><current_requests></current>
            <maximum><maximum_requests_per_day></maximum>
        </requests>
    </meta>
    <data/>
</response>

Time Zones

All times must be sent and will be reported in Eastern Time. Times are representative of Daylight Savings Time.


HTTP Methods

The following are the HTTP methods used for interacting with the API:

GET Gets an object or list of objects
POST Creates a new object
PUT Updates an object
DELETE Deletes an object

 

Response

A response can be inspected on 2 different levels:

  • The HTTP response code and message within the meta→status node of the response
  • The HTTP response code and message within the response headers

 

The following are the HTTP response status codes that apply to using this service:

200 Success The body of the response may be consumed immediately.
201 Created The object has been created.
204 Deleted The object has been deleted.
400 Invalid Parameters Clients must not attempt to perform subsequent requests using the same parameters.
401 Authentication Error Clients must authenticate to use any part of the service.
403 Forbidden Clients are unauthorized to access portion of the service.
404 Not Found Client is attempting to access a resource that doesn't exist.
405 Method Not Allowed The HTTP methods being used is not permitted. Allow header will contain allowable methods.
409 Logical Conflict Client is attempting to perform an operation on a object that conflicts with the state of the object.
429 Too Many Requests/Concurrency Limit Client has sent too many requests in a given amount of time or the maximum number of concurrent connections has been exceeded.
500 Internal Server Error Indicates that an unexpected error has occurred on the server; clients may attempt to issue another request at a later date when the problem has been resolved.

 

Authentication

Generate Advertiser API Key

The API requires an API Key for Pepperjam to authenticate you as a user. This key is required for all API requests.