Certain API 2.0

API

Developer Info

Certain API 2.0 is a set of REST methods provided as part of the Certain platform. The REST methods are URLs that are invoked over the Internet using HTTPS. Each URL identifies the path to one or more business object resources. These URLs enable retrieval of a single business object resource or a list (collection) of these resources. Depending upon the type of business object, new resources can also be created, updated or deleted.

In order to use Certain API 2.0, a valid username and password must be specified with the request. The username and password are authenticated against the database of authorized users for the resource. After successful authentication, access authorization is checked for the resource and if satisfied, the requested operation is performed.

Certain API 2.0 uses standard HTTP method semantics, where retrieval of resources is requested with an HTTP GET, new resources are created with an HTTP POST, and existing resources can be updated with HTTP POST and deleted with HTTP DELETE. The specific operation and their options depend on the type of business object resource.



Standards Compliance


Basic Authentication - Certain API 2.0 requires requests be made over HTTPS. Username and password are provided in the request using the Basic Authorization header as defined in RFC 2617 by the IETF. This specification can be found at http://www.ietf.org/rfc/rfc2617.txt

This mechanism is broadly supported by HTTP integration products and by web browsers, and provides a sufficiently secure method of request authentication when implemented with the HTTPS protocol.


Sample URL's


Generic REST URLs

Business Object Resource Path Elements


Each resource in Certain API 2.0 is identified by a path, which is similar to the naming of files in directory trees on a computer. The path to a specific business object resource is specified as /accountCode/eventCode/registrationCode. The path to the list (collection) of business objects for an event is /accountCode/eventCode. These path elements are described in the following paragraphs.


Host

The host is your configured domain.


AccountCode

The accountCode is specified in the Certain application when an account (or sub-account) is created. It is a customer-defined value which should have some meaning to the business entity, or the department within a business entity, that is conducting events. For instance, "marketing".


EventCode

The eventCode is specified in the Certain application when an event is created. It is a customer-defined value that should have some meaning to the business in relation to the specific event. For instance, "CPUG2013".


RegistrationCode

The registrationCode is automatically generated for each registration created for an event.


Content Type


The GET method will return XML or JSON based on the request Accept header provided by the caller. If no Accept header is provided, JSON format will be returned. Note that most browsers will specify XML in their request's Accept header. See the examples for details on specifying the Accept header.


Query Parameters


Query parameters are optional and can be specified at the end of the registration object path, following a question mark and with each parameter separated from the others by an ampersand (&), as per the normal HTTP query parameter syntax. The following parameters are supported:

  • filterBy - only include the data that meets the specified filter criteria
  • filterType - determines whether the filters are "AND" or "OR" conditions:
    • filterType =AND/OR, defaults to AND
  • orderBy - order the returned data by the specified field
  • pageControls - specifies the subset of the selected records to return
  • max_results - nnn where nnn is the maximum number of results to return
  • includeList - include additional data not returned in the default response
  • prohibitedList - exclude data returned in the default response
  • listFields - only return a specified subset of fields - only applies to the Registration object (see the Registration: Get reference for more information)

View the individual objects for more detail on the parameters that are supported per object.


Testing


We recommend using a REST Test client such as Rest Client for Firefox or Postman for Chrome. Testing using a web browser while also logged into Certain can result in 500 error, particularly for the User Conference business objects.


Example


Url:- https://app.certain.com/certainExternal/service/{ServiceUrl}


e.g. for account service
serviceUrl is v1/Account/{accountCode}/{eventCode}
if accountCode= Dell and eventCode= Promotion

then url will be https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion


GET

HTTP METHOD - GET

URL - https://app.certain.com/certainExternal/service/v1/{service name}/{accountCode}/{eventCode}

HEADERS -

Accept :- application/json

Username: username

Password : password

REQUEST BODY- Not Applicable


Filters (Optional) -

Results can be filtered by specifying filters(check supported filters).

e.g filter results by accountCode then url will be

https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion?accountCode=Dell

Order By (Optional) -

Results can be sorted by specifying orderBy (check supported orderBy).

e.g sort results by dateCreated (ascending order) then url will be

https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion?orderBy=dateCreated_asc


DELETE

HTTP METHOD - DELETE

URL - https://app.certain.com/certainExternal/service/v1/{service name}/{accountCode}/{eventCode}

HEADERS -

Accept :- application/json

Username: username

Password : password

REQUEST BODY- Not Applicable


POST

HTTP METHOD - POST

URL - https://app.certain.com/certainExternal/service/v1/{service name}/{accountCode}/{eventCode}

HEADERS -

Accept :- application/json

Content-Type :- application/json

Username: username

Password : password

REQUEST BODY-

{
   "accountCode": "accountCodeXYZ",
   "accountCode": "eventCode": "eventCodeXYZ",
   "accountCode": "speakerCode": 477,
   "firstName": "firstNameXYZ",
   "middleName": "middleNameXYZ",
   "lastName": "lastNameXYZ",
   "pic": "picXYZ",
   "bio": "bioXYZ",
   "email": "emailXYZ",
   "organization": "organizationXYZ",
   "isActive": true
   }

Note: API supports json and xml both type of contents, example given above uses json type.


API Rate Limit Enforcement FAQ


    1. 1. What is the API rate limit?

      2. 20 concurrent connections

    1. 2. Why is there a rate limit?

      2. To ensure fair usage and maintain the stability of the API and services. Similar limits are common industry-wide to prevent service abuse and ensure reliability.

    1. 3. What will happen if I exceed the limit?

      2. The system will return a 429 error ("Too Many Requests"). Retry after a specified time.

    1. 4. What is a 429 error?

      2. A 429 error is an HTTP status code for too many requests within a short time. We suggest a retry after 2 seconds and use an exponential backoff strategy.

    1. 5. How does this protect customers?

      2. Enforcing rate limits prevents excessive requests that could slow down or disrupt service for all users.

    1. 6. How do I avoid hitting the rate limit?

      2. Monitor API usage, implement a retry mechanism with a backoff strategy, and avoid concurrent requests that could trigger the rate limit.

    1. 7. Developer Best Practices for Managing API Rate Limits:

      • Implement Exponential Backoff: Gradually increase the wait time after a 429 error to avoid further congestion.
      • Monitor and Optimize API Calls: Review integration for minimal API calls; batch or cache responses when possible.
      • Handle 429 Errors Gracefully: Design systems to log 429 errors, retry after the specified time, and notify users if delays occur.
      • Queue Requests: Use a queuing mechanism to distribute requests over time.
      • Parallelism Controls: Limit concurrent requests to stay within the rate limit.
      • API Usage Monitoring: Set up real-time monitoring for proactive rate limit management.

    1. 8. What if I need more concurrent connections?

      2. Contact your customer success manager to discuss your use case.

    1. 9. Does the rate limit affect all customers?

      2. Yes, this applies to all API users to ensure fair usage.

    1. 10. Will this rate limit be adjusted in the future?

      2. We may adjust limits based on overall system health and customer needs.

    1. 11. Who can I contact if I have more questions?

      2. Please reach out to your customer success manager.