General Specifications

The OptimalResume API platform is based on REST principles and provides simple and powerful web services to interact with our proprietary data, logic, and presentation assets. Our APIS are designed to provide predictable, resource-oriented URLs and HTTP response codes to indicate API errors. Developers can use our unique suite of APIs to create a variety of career services and solutions including custom applications, websites, widgets, and other projects.
API endpoints
All API access is over HTTPS, and accessed from the https://api.optimalresume.com domain.
Communications Protocol
All API requests must be made over HTTPS
Media Types
All requests and responses are formatted as JSON, including errors.

The accepted media types for Accept request header (used to specify media types which are acceptable for the response) are:

                        application/vnd.{api-name}.{api-version}+json 
application/hal+json;
application/json;

The accepted media types for Content-Type request header (used to specify the media types allowed for submitted content) are:

                        application/vnd.{api-name}.{api-version}+json 
application/json;


The media types for Content-Type response header are:

                         application/hal+json; - for a result that contains HAL-compliant links 
application/problem+json; - for a result that contains errors
application/json; - for all other responses
API Versioning
There are two different ways to specifiy versioning:
In the URL e.g. https://api.optimalresume.com/v1/optimal-interview/questions
By Accept header e.g. Accept:application/vnd.optimal-interview.v1+json
Date Format
All API dates and times are returned in ISO 8601 format.

                            YYYY-MM-DDTHH:MM:SSZ

                    
Errors
Our APIs use conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate a problem on our servers.

We provide details about errors in the body of the response in the following format:


Attributes description
type a URL to a document describing the error condition
title a brief title for the error condition
status the HTTP status code for the current request
detail error details specific to this request
{
    "validation_messages": {
        "name": {
            "isEmpty": "Value is required and can't be empty"
        }
    },
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "Failed Validation"
}
Hypermedia
One of the key features of the OptimalResume REST API platform is HAL (Hypertext Application Language).

At its core, HAL provides a set of conventions for consistent and easy API interaction through hyperlinks in JSON. With each call you make to the API, we’ll return an array of links that allow you to request more information about a call and to further interact with the API. These are meant to provide explicit links so that API clients don’t need to construct links on their own. HAL links are contextual, so you only get the information that is relative to a specific request.

The media type for the Content-Type response header when using HAL over HTTP is application/hal+json

The example below is how we represent a collection of questions using HAL:

Attributes description
self The URI of the main resource being represented expressed with a self link. Each resource will be structured as a HAL resource, and contain at least a “_links” property with a “self” relational link.
first It is pointing to the first page of resources
last It is pointing to the last page of resources
prev It is pointing to the previous page of resources
embedded The embedded property is used to represent other resources (with their own links and properties) embedded in the resource we are representing.
{
    "count": 2,
    "total": 4,
    "_links": {
        "self": {
            "href": "https://api.optimalresume.com/interview/questions?question_title=question&page=1"
        },
        "first": {
            "href": "https://api.optimalresume.com/interview/questions?question_title=question"
        },
        "last": {
            "href": "https://api.optimalresume.com/interview/questions?question_title=question&page=1"
        }
    },
    "_embedded": {
        "questions": [
            {
                "id": "AFFFDp",
                "question_title": "Do you have any questions for us?",
                "interviewer": {
                    "id": "AFFFFJ",
                    "name": "David",
                    "photo": "https://api.optimalresume.com/images/interviewers/david-big.jpg"
                },
                "status": "active",
                "create_date": "2008-05-13T18:00:00-0400",
                "update_date": "2012-06-07T11:30:00-0400",
                "_embedded": {
                    "question_source": {
                        "id": "AFFFFA",
                        "name": "Optimal Resume",
                        "_links": {
                            "self": {
                                "href": "https://api.optimalresume.com/app/AFFFFA"
                            }
                        }
                    },
                    "coaching": [
                        {
                            "id": "AFFFDc",
                            "coaching_text": "Discussion:  Asking good questions are often an indication of your interest level in the job but do not feel compelled to just throw something out there.  You may want to ask questions about the company culture, where they see future growth or what the major challenges are ahead. Response:  You have answered my questions very thoroughly and I have learned a lot about your company from my research.  Now that we have had a chance to interview, can you tell me how I did.  Am I a viable candidate for this position?",
                            "create_date": "2008-05-13T18:12:00-0400",
                            "update_date": "2012-06-07T11:32:00-0400",
                            "_links": {
                                "media_flash": {
                                    "href": "https://api.optimalresume.com/interview/coaching-video/AFFFDc?format=flash"
                                },
                                "media_mp4": {
                                    "href": "https://api.optimalresume.com/interview/coaching-video/AFFFDc?format=mp4"
                                },
                                "media_player": {
                                    "href": "https://api.optimalresume.com/interview/coaching-video/AFFFDc?format=player"
                                },
                                "self": {
                                    "href": "https://api.optimalresume.com/interview/coaching/AFFFDc"
                                }
                            }
                        }
                    ]
                },
                "_links": {
                    "media_flash": {
                        "href": "https://api.optimalresume.com/question-video/AFFFDp?format=flash&interviewer=david"
                    },
                    "media_mp4": {
                        "href": "https://api.optimalresume.com/question-video/AFFFDp?format=mp4&interviewer=david"
                    },
                    "media_player": {
                        "href": "https://api.optimalresume.com/question-video/AFFFDp?format=player&interviewer=david"
                    }
                }
            },
            {
                "id": "AFFF8Z",
                "question_title": "What additional questions can I answer for you?",
                "interviewer": {
                    "id": "AFFFFJ",
                    "name": "David",
                    "photo": "https://api.optimalresume.com/images/interviewers/david-big.jpg"
                },
                "status": "active",
                "create_date": "2008-05-13T18:00:00-0400",
                "update_date": "2012-06-07T11:30:00-0400",
                "_embedded": {
                    "question_source": {
                        "id": "AFFFFA",
                        "name": "Optimal Resume",
                        "_links": {
                            "self": {
                                "href": "https://api.optimalresume.com/app/AFFFFA"
                            }
                        }
                    },
                    "coaching": [
                        {
                            "id": "AFFFu0",
                            "coaching_text": "Discussion:  The interviewer may be trying to gage much you know about their organization and your level of motivation. Your pre-interview research is critical here.  Do not ask things early on such as what the benefits are or what the salary is, but rather demonstrate that you taken the time to learn about the industry and the job and that you have specific interest in the position.  Stroke the corporate ego as appropriate. Response:  The interview has been very informative and I have read a lot about your company and the industry.  This is the type of company I would like to work for and the position is exactly what I am seeking.  My I ask you what you think my changes are for continuing in the interview process at this point?   ",
                            "create_date": "2008-05-13T18:12:00-0400",
                            "update_date": "2012-06-07T11:32:00-0400",
                            "_links": {
                                "media_flash": {
                                    "href": "https://api.optimalresume.com/interview/coaching-video/AFFFu0?format=flash"
                                },
                                "media_mp4": {
                                    "href": "https://api.optimalresume.com/interview/coaching-video/AFFFu0?format=mp4"
                                },
                                "media_player": {
                                    "href": "https://api.optimalresume.com/interview/coaching-video/AFFFu0?format=player"
                                },
                                "self": {
                                    "href": "https://api.optimalresume.com/interview/coaching/AFFFu0"
                                }
                            }
                        }
                    ]
                },
                "_links": {
                    "media_flash": {
                        "href": "https://api.optimalresume.com/question-video/AFFF8Z?format=flash&interviewer=david"
                    },
                    "media_mp4": {
                        "href": "https://api.optimalresume.com/question-video/AFFF8Z?format=mp4&interviewer=david"
                    },
                    "media_player": {
                        "href": "https://api.optimalresume.com/question-video/AFFF8Z?format=player&interviewer=david"
                    }
                }
            }
        ]
    }
}
Pagination
Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the ?page parameter.
Encoding
All APIs expect all data to be UTF-8-encoded.
API Rate Limiting
For authenticated requests, the rate limit allows you to make up to 2000 requests per hour. *Note: non-partner developers are limited to 10 requests per hour.
One way to avoid exceeding the hourly rate limit is by caching API responses. Store API responses locally, especially if you expect a lot of traffic.
Please try to limit your calls to the API to a reasonable frequency. We may permanently block access if your app is calling the API too frequently, or you are requesting an unreasonable amount of data in a short time.
We’ll return a couple headers with each API request to let you know how you’re doing:
  • X-RateLimit-Limit: 2000
  • X-RateLimit-Remaining: 435
Authentication
All of our APIs require authentication. We use OAuth 2.0 to provide authorized access to our APIs. The OAuth 2.0 authorization framework enables a third-party application to obtain limited and secure access to protected resources. With each API call, you'll need to set up your request headers, including an OAuth 2.0 access token. To start making API requests, follow follow these steps

Not registered yet? Create a developer account.