Jobcast Social Recruitment App API

Response Formats

Our API responds with a JSON serialized object in the body. The one notable exception is a 503 response where we serve HTML instead of JSON.

Success Response Status Codes

Status Code Name Description
200 OK

Standard response for successful requests.

Example:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 135

{"data":[{"id":1,"name":"Full-time"},{"id":2,"name":"Part-time"},{"id":3,"name":"Contract"},{"id":4,"name":"Temporary"}],"warnings":[]}
201 Created

The request was fulfilled and resulted in a new resource being created. An HTTP Location header is included in the response.

Example:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: https://app.jobcast.net/api/v1.0/jobcategories/123
Content-Length: 69

{"data":{"id":38,"name":"Forestry","company":{"id":3}},"warnings":[]}
204 No Content

Resource was successfully deleted.

Example:

HTTP/1.1 204 No Content

Success Response Body

With the exception of 204 status (which doesn't contain a response body), all success responses will contain a JSON serialized object with common root properties.

Property Type Description
data Array or Object Contains either an array of resources or a single resource representation. This property will always exist for 200 and 201 responses.
warnings Array of strings Will contain an array of warnings for the response. This property will always exist for 200 and 201 responses, but will be empty if there are no warnings.

Error Response Status Codes

Status Code Name Description
400 Bad Request

The request was invalid. Please review the messages and try again.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 85

{"error":{"messages":["Application Email is invalid."],"type":"ValidationException"}}
401 Unauthorized

Not authorized to make the request.

Example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 84

{"error":{"messages":["Unauthorized access."],"type":"UnauthorizedAccessException"}}
404 Not Found

Resource was not found.

Example:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 90

{"error":{"messages":["Resource /api/v1.0/countries/10000 not found."],"type":"NotFoundException"}}
405 Method Not Allowed There is currently a bug with 405 responses. See Known Issues for more info.
500 Internal Server Error

An unexpected error occurred on the server. Whenever this error occurs, our developers are notified immediately and will try to solve the problem as soon as possible.

Example:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
Content-Length: 147

{"error":{"messages":["There was an unexpected error. We\u0027ll fix this and have things back to normal soon."],"type":"InternalServerException"}}
503 Service Unavailable

Server is undergoing maintenance and is not available.

This is the only response where HTML is served instead of JSON.

Error Response Body

With the exception of 503 status, all error responses will contain a JSON object with a single error property.

Example:

{
    "error":{
        "messages":[
            "Application Email is invalid."
        ],
        "type":"ValidationException"
    }
}
This error property contains an Error object, which is defined as follows.

Property Type Description
messages Array of strings

An array of error messages.

Example:

["Title is required.","City is required."]
type String

Type of error and will be one of the following:

Type Status Code Description
UnauthorizedAccessException 401 User not authorized to make the request.
InvalidCredentialsException 401 Authentication failed.
ValidationException 400 Failed validation. Refer to messages property for more info.
ConcurrencyException 400 Attempted to change resource at the same time as someone else. If you receive this error, please try again.
ArgumentException 400 JSON request contains an invalid argument. Refer to messages property for more info.
Example: "messages":["Unknown JobType identifier 10."]
InvalidOperationException 400 Tried to perform an operation that is invalid. Refer to messages property for more info.
Example: {"messages":["Published job does not allow company to change."]
NotSupportedException 400 Tried to perform an operation that is invalid. Refer to messages property for more info.
Example: "messages":["Changing system category not supported."]
InternalServerError 500 An unexpected error occurred on the server. Whenever this error occurs, our developers are notified immediately and will try to solve the problem as soon as possible.

Paging Information for Long Lists

If lists are long, the API returns partial results in a single page. The representation includes a paging object with the following properties:

Property Type Description
total Int32 Total number of records available.
pageSize Int32 The size of a page.
page Int32 The current page.
pages Int32 Total number of pages.
previous String URI to the previous page if it exists. If it doesn't exist, this will be null.
next String URI to the next page if it exists. If it doesn't exist, this will be null.

Data Formats

Dates & Times

All dates and times in requests and responses are in ISO 8601 format. For dates without a time part, it will look like this:

2012-05-25

For dates with a time part, it will look like this for UTC:

2012-05-25T13:00+0000

and like this for user specific time. The user is the owner of the User API Key.

2012-05-25T13:00-0700

The above time can be interpreted as May 25, 2012 at 13:00 user time or May 25, 2012 at 20:00 UTC.