Dev logo
API Walkthrough
Resources

API Documentation v2.0


Introduction

The OrgSync API is available to all customers with a Web Services API subscription. The API provides programmatic access to a large amount of OrgSync functionality, allowing customers to extend the OrgSync platform. This page is targeted at developers; for more general API information, see the Getting Started page.

Schema

All API access is over HTTPS, using the standard set of HTTP verbs (POST, GET, PUT, DELETE) for CRUD operations (respectively). Data is returned in JSON format. All API endpoints begin with https://api.orgsync.com/api/v2/. Please note that OrgSync requires SNI (Server Name Identification) in order to successfully connect to the API.

Parameters to requests can be passed via either URL params or via the POST body as JSON, assuming the Content-type header is appropriately set to application/json. That said, the following two calls are equivalent:

  curl -d '{ "account_id": 2, "number": 12345, "key": "dd6b9d2beb614611c5eb9f56c34b743d1d86f385" }' \
    'https://api.orgsync.com/api/v2/identification_cards' \
    --header 'Content-Type: application/json'

  curl -X POST \
    'https://api.orgsync.com/api/v2/identification_cards?key=dd6b9d2beb614611c5eb9f56c34b743d1d86f385\
     &account_id=2&number=12345'
  

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format, GMT:

YYYY-MM-DDTHH:MM:SSZ

Authentication

The first step is to obtain your API Key from your OrgSync Campus Administrator. The API Key is a multi-character string that can be found on the Community Settings page under the Setup tab. This key must be passed in all API requests via the key parameter. Failing to pass a valid key parameter will result in a 401 Unauthorized status code. You can also authenticate by passing a valid API key in an X-OrgSync-API-Key HTTP header.

HTTP Verbs

Where possible, API v2 strives to use appropriate HTTP verbs for each action:

GET

Used for retrieving resources. All requests made using this method are idempotent.

POST

Used for creating resources.

PUT

Used for updating resources.

DELETE

Used for deleting resources.

Client Errors

Whenever a request is not successful, the API will return a non-200 OK status and try to provide a useful error message in the following format:

  curl -i 'https://api.orgsync.com/api/v2/accounts/424242?key=dd6b9d2beb614611c5eb9f56c34b743d1d86f385'

  HTTP/1.1 404 Not Found
  Connection: close
  Date: Thu, 21 Jun 2012 17:08:16 GMT
  X-UA-Compatible: IE=Edge
  X-Runtime: 2.398011
  Content-Type: application/json; charset=utf-8
  Content-Length: 52
  Cache-Control: no-cache

  {"message":"Couldn't find Account with id = 424242"}
  
  1. Failing to pass a valid key parameter for authentication will result in a 401 Unauthorized response.
  2. Trying to access a resource which does not exist (by id or other attribute, like username) will result in a 404 Not Found response.
  3. Sending invalid attributes for a resource will result in a 422 Unprocessable Entity response, and, usually, a detailed error message explaining the issues with the attributes passed.