Logo

General principles

We'll take a look at the general principles about our api.

Endpoints

All our endpoints start with: https://housecheck.be/api

Except the authorization requests will be made to https://housecheck.be/oauth

Requests

All methods must be called using HTTPS.

Data is passed as JSON data in a POST request.

Example:

Body

{
    "address1": "Brusselsesteenweg",
    "address2": "34",
    "city": "Meise",
    "postal_code": "1869",
    "contact_name": "Jan Janssen",
    "contact_email": "jan@janssen.be",
    "contact_phone1": "025826232",
    ...
}

Responses

All responses are returned as JSON objects.

Pagination

Responses may also contain meta data for pagination.

Sample response with pagination:

Example:

Response

{
    ...
"links": {
        "first": "https://housecheck.be/api/orders?page=1",
        "last": "https://housecheck.be/api/orders?page=297",
        "prev": null,
        "next": "https://housecheck.be/api/orders?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 297,
        "links": [
            {
                "url": null,
                "label": "« Vorige",
                "active": false
            },
            {
                "url": "https://housecheck.be/api/orders?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "...",
                "active": false
            },
            {
                "url": "https://housecheck.be/api/orders?page=296",
                "label": "296",
                "active": false
            },
            {
                "url": "https://housecheck.be/api/orders?page=2",
                "label": "Volgende »",
                "active": false
            }
        ],
        "path": "https://housecheck.be/api/orders",
        "per_page": 15,
        "to": 15,
        "total": 4443
    }
}

Errors

Errors are always returned as a JSON object.

Example:

Response

{
    "success": false,
    "message": "Validation errors",
    "data": {
        "breaker_boxes": [
            "The breaker boxes field is required."
        ]
    }
}

Rate limiting

To ensure a fast and predictable experience for everyone, we limit the number of calls your integration (or client id) can make. You are limited to 10 requests per second.

Before allowing requests, we check how many requests your integration made in the last minute. If you would cross your limit, we deny the request by replying with a specific HTTP error.

HTTP 429 Too Many Requests

Status codes

When objects are created, we return a 201 response containing the id of the new resource.

Example:

Response

{
    "id": 150217
}

When objects are updated, we return an empty response with a 204 status code.

Common used status codes:

  • 200 OK

  • 201 Created, when resources are created

  • 204 Updated, when resources are updated

  • 400 Bad request (something wrong with URL or parameters)

  • 404 Not Found (page or other resource doesn't exist)

  • 401 Unauthorized, invalid or missing access token

  • 403 Forbidden, not allowed to access this resource

  • 422 Unprocessable Entity (validation failed)

  • 429 Too Many Requests, your client has reached the API rate limit

  • 500 General server error