Conventions

Request & response body format

Raisely always consumes and sends JSON. When you're receiving a resource from the API, the document will be contained within the data key. For example:

// GET /users/me
{
	"data": {
		"firstName": "Ryan",
		"lastName": "Raisely",
		"email": "[email protected]",
		// ...etc
	}
}

Likewise, when creating or updating a resource, your document should be wrapped in data in the request body.

Index methods will always return an array in data along with a pagination object.

// GET /users
{
    "data": [
        { /* document */ },
        { /* document */ },
    ],
    "pagination: {
        "limit": 20,
        "offset": 0,
        "pages": 42,
        "next_url": "https://api.raisely.com/...",
        "prev_url": false,
        "total": 848
    }
}

Updating Documents

Updates to a document are sent using the PATCH HTTP method. You can also PUT to these endpoints, but it will behave like a PATCH.

Only the specified fields will be changed. If you want to explicitly clear a field, you must set it to null.

Public & Private Data

Most Raisely resources have a concept of public and private data. This is how you store custom fields when someone registers, creates a profile or donates. Public and private data is contained within an object on the document.

Beyond user-set private data, some resources will also have information that is not for public consumption. For example, emails on donations are considered private even through they're not within the private JSON object.

By default the API won't return private data regardless of your authentication. You need to specify that you want private data in the URL, we'll check you're allowed to see it then return it in the response.

To request private data just add ?private=true on your request URL. If you try to access private information that you're not allowed to see, you'll get an authorization error. In some cases where the authorized user is allowed to see some, but not all, private data, the response will only contain the allowed data as well as a warning noting that some data was filtered.

Updating Public & Private Data

When you update public or private custom fields, any existing fields that are unspecified will be preserved.

For example if you have an existing user model

{
  private: {
    circleOfCommitment: 'core',
  }
}

and you update that model with

{
  private: {
    didSurvey: true,
  }
}

The resulting user model will be

{
  private: {
    circleOfCommitment: 'core',
    didSurvey: true,
  }
}

If you want to overwrite all existing data and remove any unspecified custom fields, use overwriteCustomFields: true in the body of the request.

fetch('/users/3adf8230-8f30-11ea-b461-953a385eca69', {
  method: 'PATCH',
  body: JSON.stringify({
    overwriteCustomFields: true,
    private: {
      didSurvey: true,
    },
  }),
});

This will result in the user private custom fields being

{
  private: {
    didSurvey: true,
  }
}