1. API

Getting Started

This guide includes all the details you need to start building things with our API. You can download our pre-built PHP library if you plan to use the PHP programming language.

Be sure to follow our Twitter to keep up-to-date with changes to the API.

Authentication

The Elvanto API currently supports two methods of authentication. We recommend authenticating with OAuth, however we also support authenticating with an API key.

Authenticating with OAuth

We use the OAuth 2 protocol to allow websites or applications to request authorization to an Elvanto account without requiring the account username and password.

Register an Application

To authenticate using OAuth, you're going to need to register an OAuth Application. To do this, jump into your Elvanto account, go to Settings, then select Integrations. From there you'll be asked for a few details to register your OAuth app.

Once you've registered your app, it will be assigned a unique Client ID and Client Secret. You'll need to specify these two details when using our API wrappers, or if you're not going to use an API wrapper, you'll need these details when your application requests access tokens (details below).

Permissions

Any application which authenticates using OAuth must specify which permissions it requires when requesting access tokens. All valid permissions are listed below. You'll need to refer to these permissions when you follow the authentication flows described below.

  • ManagePeople Permission to manage people.
  • ManageGroups Permission to manage groups.
  • ManageServices Permission to manage services.
  • ManageSongs Permission to manage songs.
  • ManageCalendar Permission to manage calendars and events.
  • ManageFinancials Permission to manage financials.
  • AdministerAccount Permission to administer your account.

Web Application Flow

These are the steps for authenticating from a web application.

1. Direct users of your application to:

https://api.elvanto.com/oauth?type=web_server&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}

Details of query string parameters:

  • type REQUIRED - MUST be web_server
  • client_id REQUIRED - The Client ID you received when you registered your application.
  • redirect_uri REQUIRED - Where we will redirect your users once the OAuth call is made. This must be the redirect URI provided when you registered your application.
  • scope REQUIRED - The permission level requested by the integration. This is a comma separated list of valid permissions as documented above. So for example, if you wanted to request permission to manage people and administer the user's account, you would provide scope as ManagePeople,AdministerAccount (which, when URL-encoded would be ManagePeople%2CAdministerAccount)
  • state OPTIONAL - Any additional state to be included in the redirection call.

2. The user of your application approves (or doesn't approve) your application.

3. The user of your application is redirected to the redirect_uri with the following query string parameters:

  • code A unique code generated by Elvanto.
  • state Any state data provided in step 1.

4. Your application should then make a POST request to the following URL:

https://api.elvanto.com/oauth/token

Including the following data:

grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}

Details of POST data:

  • grant_type Must be authorization_code
  • client_id The client_id as per step 1.
  • client_secret This must be the secret you received when you registered your application.
  • code The code as per step 3.
  • redirect_uri The redirect_uri as per step 1.

The response to this POST request will be a JSON object of the form:

{
  "access_token": "e1e8422f78d9cf3c44b6e3d4beb065833abf",
  "expires_in": 1209600,
  "refresh_token": "6d49263f6fb7671bf1bb79ac81c63c12bc62533221"
}

Details of the response data:

  • access_token The OAuth token to use for further API calls.
  • expires_in The number of seconds for which access_token is valid.
  • refresh_token A long-lived token which can be used to obtain a new access token.

So for example, if your application initiated an OAuth exchange by directing a user to:

https://api.elvanto.com/oauth?type=web_server&client_id=1234&redirect_uri=https%3A%2F%2Fsender.example.com%2Fintegrate&scope=AdministerAccount&state=somedata

Assuming the user approved your application, Elvanto would then redirect your user to:

https://sender.example.com/integrate?code=abc123&state=somedata

Upon receiving this request, your application should then make a POST request to the following URL:

https://api.elvanto.com/oauth/token

Including the following data:

grant_type=authorization_code&client_id=1234&client_secret=4321&code=abc123&redirect_uri=https%3A%2F%2Fsender.example.com%2Fintegrate

This request would then result in the following JSON response:

{
  "access_token": "e1e8422f78d9cf3c44b6e3d4beb065833abf",
  "expires_in": 1209600,
  "refresh_token": "6d49263f6fb7671bf1bb79ac81c63c12bc62533221"
}

Non-Web Application Flow

These are the steps for authenticating from desktop or other applications.

1. Direct users of your application to:

https://api.elvanto.com/oauth?type=user_agent&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}

Details of query string parameters:

  • type REQUIRED - MUST be user_agent
  • client_id REQUIRED - The Client ID you received when you registered your application.
  • redirect_uri REQUIRED - Where we will redirect your users once the OAuth call is made. This must be the redirect URI provided when you registered your application.
  • scope REQUIRED - The permission level requested by the integration.

2. The user of your application approves (or doesn't approve) your application.

3. The user of your application is redirected to the redirect_uri with the following parameters in the hash of the URL:

  • access_token The OAuth access token to use for further API calls.
  • expires_in The number of seconds for which access_token is valid.
  • refresh_token A long-lived token which can be used to obtain a new access token.

So for example, if your application initiated an OAuth exchange by directing a user to:

https://api.elvanto.com/oauth?type=user_agent&client_id=1234&redirect_uri=https%3A%2F%2Fsender.example.com%2Fintegrate&scope=AdministerAccount

Assuming the user approved your application, Elvanto would then redirect your user to:

https://sender.example.com/integrate#access_token=abc123&refresh_token=123abc&expires_in=1209600

Errors during OAuth exchange

Error handling within the oAuth exchange depends on the type of error encountered. Errors related to end-user information (credentials, permissions etc) are shown to the end-user during the oAuth exchange, errors related to the integration will result in the end-user being sent to the redirect_uri with the details of the error included.

Possible integration errors are:

  • invalid_request Required parameters were not supplied.
  • unknown_client The client_id did not match a registered integration.
  • invalid_redirect_uri The redirect_uri did not begin with the redirect URI registered for the application.
  • server_error Something went wrong at the Elvanto end.
  • unknown_scope Unrecognised permissions were requested via the scope parameter.
  • access_denied The end-user did not grant authorisation.

Possible end-user errors are:

  • Invalid credentials.
  • Insufficient permissions - The end-user did not have the permissions required by the integration.

Refreshing Access Tokens

All access tokens granted will automatically expire after the timeframe specified when retrieving the token, so all developer code must cater for refreshing tokens.

If an access token has been granted using the Web Application Flow, you can use the refresh token included when the original token was granted to automatically retrieve a new access token. You do this by issuing a POST request to the following URL:

https://api.elvanto.com/oauth/token

Including the following data:

grant_type=refresh_token&refresh_token={refresh_token}

Details of POST data:

  • grant_type REQUIRED - MUST be refresh_token
  • refresh_token REQUIRED - The refresh_token supplied during the previous token grant

The response to these refresh token requests takes the same form as the response to the initial token grant:

{
  "access_token": "3d4beb063abfe8422f78d9cf3c447b6500e",
  "expires_in": 1209600,
  "refresh_token": "6d49263f6fb7671bf1bb79ac81c63c12bc62533221"
}

If an access token has been granted using the Non-Web Application Flow, you do not receive a refresh token when you are granted an access token. In this situation, your code will need to use the expires_in value provided in the hash of the URL, to calculate whether you need to request a new access token if the current token has expired.

Using access tokens to make API calls

When making API calls with an OAuth access token, the token should be passed in as a bearer token in the Authorization header of an API request.

So for example, if your access token was 3d4beb063abfe8422f78d9cf3c447b6500e, the authorization header of your HTTP requests would be Authorization: Bearer 3d4beb063abfe8422f78d9cf3c447b6500e.

To get a list of people in JSON format using cURL, you'd do the following:

curl -H "Authorization: Bearer 3d4beb063abfe8422f78d9cf3c447b6500e" https://api.elvanto.com/v1/people/getAll.json

Response You should receive a HTTP response similar to:

{
    "generated_in": "0.018",
    "status": "ok",
    "people": {
        "on_this_page": 50,
        "page": 1,
        "per_page": 50,
        "total": 668,
        "person": [
            {
                "id": "g534b5a4-9b2f-102c-400a-9e610b138475",
                "firstname": "John",
                "lastname": "Smith"
            },
            {
                "id": "400ab5a4-8475-102c-g534-9e610b139b2f",
                "firstname": "Sandra",
                "lastname": "Johnson"
            }
        ]
    }
}

Authenticating with an API key

You may also use an API key and HTTP Basic Authentication to authenticate API requests. You can get your API key from the Settings -> Account Settings page when logged into your Elvanto account. When you make an API request you provide your API key as the username and the password portion can be blank or a dummy value, as it is not used for authentication.

To demonstrate authentication with an API key, you can make any GET request to the API directly in your web browser. So for example, if you wanted to get a list of all your people in JSON format, you would enter the following into your address bar:

https://api.elvanto.com/v1/people/getAll.json

Your browser should then display a dialog requesting that you enter a username and password. Enter your API key (e.g. "3d4beb063abfe8422f78d9cf3c447b6500e") in the username field. You can leave the password field blank or enter a dummy value like 'x'. If your request is authenticated, you should then be delivered the JSON response.

You can also make API calls from the command line using a tool like cURL (which will also allow you to make requests which require the use of POST).

To get a list of people in JSON format using cURL, you'd do the following:

curl -u "3d4beb063abfe8422f78d9cf3c447b6500e:x" https://api.elvanto.com/v1/people/getAll.json

You should receive a HTTP response similar to:

{
    "generated_in": "0.018",
    "status": "ok",
    "people": {
        "on_this_page": 50,
        "page": 1,
        "per_page": 50,
        "total": 668,
        "person": [
            {
                "id": "g534b5a4-9b2f-102c-400a-9e610b138475",
                "firstname": "John",
                "lastname": "Smith"
            },
            {
                "id": "400ab5a4-8475-102c-g534-9e610b139b2f",
                "firstname": "Sandra",
                "lastname": "Johnson"
            }
        ]
    }
}

API Endpoint

All calls are accessed via the following endpoint:

https://api.elvanto.com/v1/SOME/METHOD.OUTPUT_FORMAT

Passing Request Data

Request data is passed to the API by POSTing JSON objects to the API endpoint with the appropriate parameters. As an alternative, you can also use HTTP POST or HTTP GET parameters, just like submitting an HTML FORM.

When providing input you must ensure that your JSON complies with the syntax paying particular attention to character and entity encoding with both formats. Any input provided in the query string of any request should be url-encoded. An example of where this is required is the request for searching a person's details which takes an email address as a query string parameter.

Example: Creating a person

To create a person, you would make a HTTP POST request:

POST
https://api.elvanto.com/v1/people/create.json JSON HTTP POST 
{
    "firstname": "John",
    "lastname": "Smith",
    "email": "me@johnsmith.com"
}

Output Formats

When you make an API request, you must specify a data format in the URL, which represents the data format in which you expect to receive output in the body of the response. Simply replace the file extension in the API Endpoint (OUTPUT_FORMAT above) with one of:

  • json (default)
  • xml
  • php

The PHP result is a serialized version of a PHP object.

Example response: JSON XML PHP 
{
    "generated_in": "0.018",
    "status": "ok",
    "person": {
        "id": "dd34b5a4-9b2f-103c-8475-9e710b13400a",
        "date_added": "2024-12-14 15:32:04",
        "date_modified": "2024-12-14 18:32:04",
        "firstname": "John",
        "lastname": "Smith",
        "email": "me@johnsmith.com",
        "phone": "(07) 6593 4857",
        "mobile": "0436 749 487",
        "admin": "1",
        "archived": "0",
        "volunteer": "1"
    }
}

Response status codes

The responses returned by the API are accompanied by meaningful HTTP status codes which represent the status of the request. Here's the general approach we take when returning responses:

Success

Requests will return a "200 OK" response if the API call is successfully processed.

Errors

If you attempt to authenticate with an invalid API key or you attempt to use an invalid ID for a resource, you'll receive a "401 Unauthorized" response.

Example response: 401 Unauthorized JSON XML PHP 
{
    "generated_in": "0.018",
    "status": "fail",
    "error": {
        "code": 102,
        "message": "Invalid API Key."
    }
}

If there is an error in your input, you'll receive a "400 Bad Request" response, with details of the error.

Example response: 400 Bad Request JSON XML PHP 
{
    "generated_in": "0.018",
    "status": "fail",
    "error": {
        "code": 250,
        "message": "No search parameters provided."
    }
}

If you attempt to request a resource which doesn't exist, you'll receive a "404 Not Found" response.

Example response: 404 Not Found JSON XML PHP 
{
    "generated_in": "0.018",
    "status": "fail",
    "error": {
        "code": 404,
        "message": "No people match your criteria."
    }
}

If an unhandled error occurs on the API server for some reason, you'll receive a "500 Internal Server Error" response.

Example response: 500 Internal Server Error JSON XML PHP 
{
    "generated_in": "0.018",
    "status": "fail",
    "error": {
        "code": 500,
        "message": "Sorry, we've run into a problem. Please try again or contact support."
    }
}