Introduction

Welcome to the Objectia® REST API.

Endpoints

All API requests are made to api.objectia.com and all requests are served over HTTPS.

https://api.objectia.com/v1

IMPORTANT

API calls made over plain HTTP are not supported and will fail.

Versioning

As we develop future versions of our API that are not backwards-compatible, we will leave the old version running and create a new url for the latest version. We will retain support for obsolete versions for a generous period of time and will send email notifications of any changes.

The current API version is v1. Future versions will be v2, v3, etc.

Authentication

All requests to the API must be authenticated with an API key. You can submit the API key in the HTTP request header, or you can specify the access token as a HTTP URL query parameter.

TIP

If you do not have an API Key, you can easily generate one by heading over to the API settings page.

In the HTTP Authorization header:

Authorization: Bearer YOUR-API-KEY

In the URL

Add api_key=YOUR-API-KEY to the URL:

https://api.objectia.com/v1/geoip/8.8.8.8?api_key=YOUR-API-KEY

IMPORTANT

API requests without authentication will fail.

Errors

Objectia uses conventional HTTP status response codes to indicate the success or failure of an API request. In general: Status codes in the 2XX range indicate success. Status codes in the 4XX range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Status codes in the 5XX range indicate an error with Objectia's servers (these are rare).

The body of an error response:

{
  "status": 404,
  "success": false,
  "code": "err-ip-not-found",
  "message": "IP address not found"
}

status is the HTTP status code, success is true upon success and false if there was an error. message is a descriptive error message string, and finally code is the error code (see below for a list of error codes).

Error codes

Code Description
err-access-denied Access was denied to the API endpoint. Check your API key permissions or IP address restrictions.
err-account-suspended Your account has been suspended due to a payment problem.
err-bad-gateway Bad gateway (DNS or routing problem, 502).
err-https-required You must use HTTPS to access the API.
err-internal-server-error Something went wrong on our side (500).
err-invalid-apikey The API key provides was not valid (wrong format or not found in our database).
err-invalid-ip You provided an invalid IP address for Geolocation lookup.
err-invalid-param The request has a missing or wrong input parameter.
err-invalid-request The request sent to the API server was incomplete or had invalid parameters.
err-invalid-sender Not allowed to send from this address.
err-ip-not-found The specified IP address was not found in the GeoIP database.
err-malware-detected Malware has been detected in outgoing mail.
err-missing-apikey You forgot to provide an API key.
err-missing-dkim Missing or invalid DKIM DNS record for sending domain.
err-missing-dmarc Missing or invalid DMARC DNS record for sending domain.
err-missing-spf Missing or invalid SPF DNS record for sending domain.
err-no-data No data available.
err-no-recipients No valid mail recipients.
err-no-route Route not found.
err-not-modified Not modified (304)
err-pro-feature This feature is not available for your plan (upgrade to the Pro plan to continue).
err-rate-limit Too may requests - rate limit exceeded.
err-service-unavailable Service unavailable (503).
err-spam-detected Outgoing mail has been flagged as spam.
err-too-many-recipients Too many mail recipients.
err-unexpected Unexpected response from server.
err-usage-exceeded You have exceeded your API usage limit.

Rate limits

API access rate limits are applied at a per-key basis in unit time. Access to the API using a key is limited to 60 requests per minute for BASIC accounts, and 600 requests per minute for PRO accounts. In addition, every API response is accompanied by the following set of headers to identify the status of your consumption.

Header Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.
X-RateLimit-Delay The number of seconds until the rate counter is reset (only present when limit has been exceeded).

Once you hit the rate limit, you will receive a response similar to the following JSON, with a status code of 429.

{
  "status": 429,
  "success": false,
  "code": "err-rate-limit",
  "message": "Too may requests - rate limit exceeded"
}

Making requests

The API returns data in either JSON or XML format. JSON is the default format. You specify the format of the return data using the Accept header. You can also specify the data format using HTTP URL query parameter format. This is particulary useful for GET requests where you cannot set HTTP headers.

The Accept header:

Accept: application/json

or

Accept: application/xml

In the URL

Add format=json or format=xml to the URL:

https://api.objectia.com/v1/geoip/8.8.8.8
  ?api_key=YOUR-API-KEY
  &format=json

or

https://api.objectia.com/v1/geoip/8.8.8.8
  ?api_key=YOUR-API-KEY
  &format=xml

POSTing data

For POST/PATCH/PUT requests you can upload data using JSON, XML, form URL encoded or multipart form data. You specify the type of content using the Content-Type header.

JSON:

Content-Type: application/json
{
  "from": "me@example.com",
  "to": ["john@example.com", "steve@example.com"],
  "subject": "Test",
  "text": "This is a test"
}

XML:

Content-Type: application/xml

You must enclose an XML request inside a <request> tag.

<request>
	<from>me@example.com</from>
	<to>john@example.com</to>
	<to>steve@example.com</to>
	<subject>Test</subject>
	<text>This is a test</text>
</request>

Form URL encoded:

Content-Type: application/x-www-form-urlencoded

Multipart form data:

Content-Type: multipart/form-data; boundary="someboundary"

Responses

Single-item responses will be in this format:

JSON:

{
  "status": 200,
  "success": true,
  "data": {
    "id": 1,
    "name": "test"
  }
}

or XML:

<result>
    <status>200</status>
    <success>true</success>
    <data>
        <id>1</id>
        <name>test</name>
    </data>
</result>

Most endpoints return a single model of data.

Multi-item responses will be in this format:

JSON:

{
  "status": 200,
  "success": true,
  "data": [
    { 
      "id": 1,
      "name": "test1"
    },
    { 
      "id": 2,
      "name": "test2"
    }
  ]
}

or XML:

<result>
    <status>200</status>
    <success>true</success>
    <dataset>
       <data index="0">
          <id>1</id>
          <name>test1</name>
       </data> 
       <data index="1">
          <id>2</id>
          <name>test2</name>
       </data> 
    </dataset>
</result>    

NOTE: The data index starts from zero for XML arrays.

JSON Callbacks

The Objectia API also supports JSONP callbacks. To use this feature, add callback=CALLBACK_FUNCTION to the HTTP request, and the result set will be returned as the callback function you specified.

Example request:

https://api.objectia.com/v1/geoip/8.8.8.8
  ?api_key=YOUR-API-KEY
  &callback=CALLBACK_FUNCTION

Example response:

CALLBACK_FUNCTION({
  "data": {
    "country_code": "US"
  },
  "status": 200,
  "success": true
})    

Formatted output

By default the output from the Objectia API is not formatted in any way. In order to improve readability you can specify that you want the output to be formatted and indented.

To enable this feature, add indented=true to the API request:

https://api.objectia.com/v1/geoip/8.8.8.8
  ?api_key=YOUR-API-KEY
  &indented=true

IMPORTANT

Indented output is larger than normal output and should only be used for debugging purposes.

Your use and access to the API is expressly conditioned on your compliance with the policies, restrictions, and other provisions related to the API set forth in our Terms of Service and the Privacy Policy, in all uses of the API. If we believes that you have or attempted to violate any term, condition, or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.

Objectia is a registered trademark of UAB Salesfly.