Reimbursements

This section describes the API of the reimbursement resource.

Parameters

id: integer
description: string
amount: float
tags: array
currency: string
based on currencies code
payer: JSON object
receiver: JSON object
responsible user: JSON object
expenses: array of objects
array of an expense representation
activities_count: integer
comments_count: integer
created_at: string
updated_at: string
_links: array of object
array of links of the reimbursement

Example of Reimbursement

    {
      "id": 1,
      "description": "Reimbursement example 1",
      "amount": 120.00,
      "currency": "BRL",
      "tags": ["tag 1", "tag 2"],
      "payer": {
        "id": 1,
        "name": "Company Inc.",
        "type": "Organization",
        "logo": [
          {
            "style": "original",
            "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/original/logo.png",
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "medium",
            "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/medium/logo.png",
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "thumb",
            "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/thumb/logo.png",
            "expiration": "2014-06-27T20:31:43Z"
          }
          {
            "style": "tiny",
            "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/tiny/logo.png",
            "expiration": "2014-06-27T20:31:43Z"
          }
        ]
      },
      "receiver": {
        "id": 1,
        "name": "John",
        "type": "User",
        "avatar": [
          {
            "style": "original",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/original/avatar.png",
            "width": 716,
            "height": 655,
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "medium",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/medium/avatar.png",
            "width": 300,
            "height": 300,
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "thumb",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/thumb/avatar.png",
            "width": 100,
            "height": 100,
            "expiration": "2014-06-27T20:31:43Z"
          }
          {
            "style": "tiny",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/tiny/avatar.png",
            "width": 48,
            "height": 48,
            "expiration": "2014-06-27T20:31:43Z"
          }
        ]
      },
      "responsible_user": {
        "id": 1,
        "name": "John",
        "type": "User",
        "avatar": [
          {
            "style": "original",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/original/avatar.png",
            "width": 716,
            "height": 655,
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "medium",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/medium/avatar.png",
            "width": 300,
            "height": 300,
            "expiration": "2014-06-27T20:31:43Z"
          },
          {
            "style": "thumb",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/thumb/avatar.png",
            "width": 100,
            "height": 100,
            "expiration": "2014-06-27T20:31:43Z"
          }
          {
            "style": "tiny",
            "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/tiny/avatar.png",
            "width": 48,
            "height": 48,
            "expiration": "2014-06-27T20:31:43Z"
          }
        ]
      },
      "expenses": [
        {
          "id": 1,
          "description": "Expense example 1",
          "amount": 120.00,
          "approved_amount": 100.00,
          "approved_amount_currency": "USD",
          "status": "awaiting_analysis",
          "occurred_at": "2014-06-01T14:17:56Z",
          "payer": {
            "id": 1,
            "name": "Company Inc.",
            "type": "Organization",
            "logo": [
              {
                "style": "original",
                "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/original/logo.png",
                "expiration": "2014-06-27T20:31:43Z"
              },
              {
                "style": "medium",
                "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/medium/logo.png",
                "expiration": "2014-06-27T20:31:43Z"
              },
              {
                "style": "thumb",
                "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/thumb/logo.png",
                "expiration": "2014-06-27T20:31:43Z"
              }
              {
                "style": "tiny",
                "url": "https://rexpense-uploads.s3.amazonaws.com/organization_logo/1/tiny/logo.png",
                "expiration": "2014-06-27T20:31:43Z"
              }
            ]
          },
          "receiver": {
            "id": 1,
            "name": "John",
            "type": "User",
            "avatar": [
              {
                "style": "original",
                "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/original/avatar.png",
                "width": 716,
                "height": 655,
                "expiration": "2014-06-27T20:31:43Z"
              },
              {
                "style": "medium",
                "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/medium/avatar.png",
                "width": 300,
                "height": 300,
                "expiration": "2014-06-27T20:31:43Z"
              },
              {
                "style": "thumb",
                "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/thumb/avatar.png",
                "width": 100,
                "height": 100,
                "expiration": "2014-06-27T20:31:43Z"
              }
              {
                "style": "tiny",
                "url": "https://rexpense-uploads.s3.amazonaws.com/user_avatar/1/tiny/avatar.png",
                "width": 48,
                "height": 48,
                "expiration": "2014-06-27T20:31:43Z"
              }
            ]
          },
          "attachments": [
            {
              "id": 1,
              "description": "Hotel in China",
              "uploaded_at" : "2014-06-23T14:31:14Z",
              "content_type": "image/png",
              "file_name": "expense.png",
              "url": "https://rexpense-direct-uploads.s3.amazonaws.com/uploads/1/original/expense.png",
              "user": {
                "id": 1,
                "first_name": "John",
                "last_name": "Rexpense",
                "mention_name": "JohnRexpense",
                "emails": [
                  {
                    "email": "john@rexpense.com",
                    "main": true
                  }
                ]
              }
            }
          ],
          "tags": "lunch, conference, 2014, new clients",
          "currency": "BRL",
          "latitude": -22.913444,
          "longitude": -47.051059,
          "location": "R. Cap. Pedro de Alcântara, 212 - Jardim Primavera, SP, 13026-390, República Federativa do Brasil",
          "attachments_count": 1,
          "comments_count": 1,
          "activities_count": 1,
          "liquidate_through_advancement": true,
          "created_at": "2014-06-03T14:17:56Z",
          "updated_at": "2014-06-03T14:17:56Z",
          "_links": [
            {
              "rel": "self",
              "method": "GET",
              "href": "https://app.rexpense.com/api/v1/expenses/1"
            },
            {
              "rel": "update",
              "method": "PUT",
              "href": "https://app.rexpense.com/api/v1/expenses/1"
            },
            {
              "rel": "partial_update",
              "method": "PATCH",
              "href": "https://app.rexpense.com/api/v1/expenses/1"
            },
            {
              "rel": "destroy",
              "method": "DELETE",
              "href": "https://app.rexpense.com/api/v1/expenses/1"
            }
          ]
        }
      ]
      "activities_count": 1,
      "comments_count": 0,
      "created_at": "2014-06-03T14:17:56Z",
      "updated_at": "2014-06-03T14:17:56Z",
      "_links": [
        {
          "rel": "self",
          "method": "GET",
          "href": "https://app.rexpense.com/api/v1/reimbursements/1"
        },
        {
          "rel": "update",
          "method": "PUT",
          "href": "https://app.rexpense.com/api/v1/reimbursements/1"
        },
        {
          "rel": "partial_update",
          "method": "PATCH",
          "href": "https://app.rexpense.com/api/v1/reimbursements/1"
        },
        {
          "rel": "destroy",
          "method": "DELETE",
          "href": "https://app.rexpense.com/api/v1/reimbursements/1"
        }
      ]
    }

List all reimbursements

Retrieve all reimbursements that the authenticated user can view or manage. It will return a JSON containing the name of the resource with an array of the objects requested and informations like the total of objects, current page and total pages. The fields of the reimbursements can be found in the Reimbursement section.

Parameters

page: integer
per_page: integer limit to 100

Definition

GET https://app.rexpense.com/api/v1/reimbursements

Example Request

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/reimbursements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": 1,
      "reimbursements": [{ "id": 1, ... }]
    }

Filtering a list of reimbursements

You can filter the list of retrieved reimbursements.

Parameters

All parameters must be nested in the q parameter.

amount_gteq: float
amount_lteq: float
receiver_id_eq: integer
payer_id_eq: integer
created_at_gteq: string
created_at_lteq: string
updated_at_gteq: string
updated_at_lteq: string
search_tags: string
has_tag: string
Available values: '1', '0', ''

Definition

GET https://app.rexpense.com/api/v1/reimbursements

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/reimbursements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"amount_gteq":123.63}}'

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/reimbursements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"amount_gteq":3000.00, "amount_lteq": 4000.00}}'

Response Example

    {
      "count": 20,
      "current_page": 1,
      "total_pages": 2,
      "reimbursements": [{ "id": 1, "amount": 3500.00... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/reimbursements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"receiver_id_eq": 1}}'

Response Example

    {
      "count": 0,
      "current_page": 1,
      "total_pages": 1,
      "reimbursements": [{ "id": 1, "receiver": {"id": 1, "name": "John Smith"} ... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/reimbursements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"payer_id_eq": 1}}'

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": 1,
      "reimbursements": [{ "id": 1, "payer": {"id": 1, "name": "Organization example 1"} ... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/reimbursements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"created_at_gteq": "12-24-2013", "created_at_lteq": "12-25-2013"}}'

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": ,
      "reimbursements": [{ "id": 1, "created_at": "2013-12-24T23:59Z" ... }]
    }

Request example

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/reimbursements \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json' \
      -d '{"q": {"updated_at_gteq": "12-24-2013", "updated_at_lteq": "12-25-2013"}}'

Response Example

    {
      "count": 1,
      "current_page": 1,
      "total_pages": 1,
      "reimbursements": [{ "id": 1, "updated_at": "2013-12-24T23:59Z" ... }]
    }

Show a reimbursement

This request shows the reimbursement complete information.

Parameters

id: integer required

Definition

GET https://app.rexpense.com/api/v1/reimbursements/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X POST https://app.rexpense.com/api/v1/reimbursements/1 \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json'

Response Example Success

HTTP 200 OK
    {
      "id": 1,
      ...
    }

Response Example Failure

HTTP 404 Record Not Found
    {
      "errors": {
        "message": "Record Not Found"
      }
    }

New reimbursement

To create a new reimbursement before you need to choose Reimbursement's payer, receiver and currency. Those fields are required to enable you to choose which expense to be part of the reimbursement.

Important:

  • The payer must have a relation with the receiver. Also the expenses must be approved and with the same approved currency.

Parameters

payer_id: integer required
receiver_id: integer required
currency: string required

Definition

GET https://app.rexpense.com/api/v1/reimbursements/new

Example Request

$ curl -u $YOUR_API_TOKEN:X -X POST https://app.rexpense.com/api/v1/reimbursements/new \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json' \
        -d '{"payer_id": 1, "receiver_id": 1, "currency": "USD"}'

Response Example Success

HTTP 200 OK
    {
      "id": 1,
      ...
    }

Create a reimbursement

This request creates a new reimbursement.

Important:

  • The payer must have a relation with the receiver to create a new reimbursement.

Parameters

description: string
payer: payer object attributes required
id: integer
type: string
receiver: receiver object attributes required
id: integer
type: string
amount: float required
date: string required
iso8601 format
currency: string
based on currencies code
tags: array

Expired organization

If the organization is expired, it will return an 402 error.

Definition

POST https://app.rexpense.com/api/v1/reimbursements

Example Request

$ curl -u $YOUR_API_TOKEN:X -X POST https://app.rexpense.com/api/v1/reimbursements \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json' \
        -d '{"amount": 1000.00, "date": "2013-12-24", "payer": {"id": 1, "type": "Organization"}}'

Response Example Success

HTTP 201 CREATED
    {
      "id": 1,
      ...
    }

Response Example Failure

HTTP 422 Unprocessable Entity
    {
      "errors": {
        "amount": ["can't be blank"]
      }
    }

Example Response Failure when organization is expired

HTTP 402 Payment Required
    {
      "errors": {
        "message": "This organization is expired and in read-only mode until this situation have been solved."
      }
    }

Update a reimbursement

There are two ways to update a reimbursement: partially or fully. If you'd like to change just one or a few attributes, you have to use the HTTP method PATCH. If you use the HTTP method PUT, you'll have to pass all attributes of the reimbursement. This behaviour is the same for all resources in the Rexpense API.

Parameters

description: string
payer: payer object attributes required
id: integer
type: string
receiver: receiver object attributes required
id: integer
type: string
amount: float required
date: string required
currency: string
tags: array

Expired organization

If the organization is expired, it will return an 402 error.

Definition

PUT/PATCH https://app.rexpense.com/api/v1/reimbursements/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X PATCH https://app.rexpense.com/api/v1/reimbursements/:id \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json' \
        -d '{"amount": 1200.00, "date": "2014-12-28"}'

Response Example Success

HTTP 200 OK
    {
      "id": 1,
      ...
    }

Response Example Failure

HTTP 422 Unprocessable Entity
    {
      "errors": {
        "date": ["can't be blank"]
      }
    }

Example Response Failure when organization is expired

HTTP 402 Payment Required
    {
      "errors": {
        "message": "This organization is expired and in read-only mode until this situation have been solved."
      }
    }

Destroy a reimbursement

To destroy a reimbursement you have to own the reimbursement (be the receiver) or be an Organization's Administrator or Manager (have any relation with the payer).

Expired organization

If the organization is expired, it will return an 402 error.

Definition

DELETE https://app.rexpense.com/api/v1/reimbursements/:id

Example Request

$ curl -u $YOUR_API_TOKEN:X -X DELETE https://app.rexpense.com/api/v1/reimbursements/:id \
        -H 'Accept: application/json' \
        -H 'Content-type: application/json'

Response Example

HTTP 204 NO CONTENT

Example Response Failure when organization is expired

HTTP 402 Payment Required
    {
      "errors": {
        "message": "This organization is expired and in read-only mode until this situation have been solved."
      }
    }

Reimbursement's activities

Activities are simple logs from a Reimbursement's changes or comments activities.

If the activity is a Reimbursement change, the response will hide the source element from the response.

If the activity is a Comment and the content have emojis, they will be rendered as text code by default (for example, :smile:). However, if you'd like to get the unicode of the emojis instead, you should supply a emoji_in_unicode boolean param.

Parameter

emoji_in_unicode: boolean

Definition

GET https://app.rexpense.com/api/v1/reimbursements/:reimbursement_id/activities

Example request

$ curl -u $YOUR_API_TOKEN:X -X GET https://app.rexpense.com/api/v1/reimbursements/1/activities \
      -H 'Accept: application/json' \
      -H 'Content-type: application/json'

Response Example Success

HTTP 200 OK
    {
      "changes": "John made a new comment: This is my first comment.",
      "occurred_at": "2014-06-01T14:17:56Z",
      "source": {
        "id": 1,
        "type": "Comment"
        ...
      },
      "user": {
        "id": 1,
        ...
      }
    }