Queries

To ensure you get only the most relevant results with reasonable performance, the Lighthouse API supports filtering, pagination, sorting, and search capabilities.

Overview

The Lighthouse API provides flexible querying options to help you retrieve exactly the data you need. Although specific endpoints may support only some of the described functionality, this page provides generic rules for making requests with these query features.

Key Capabilities

  • Filtering - Narrow results using date ranges and field-specific criteria
  • Pagination - Retrieve data in manageable chunks with offset and limit
  • Sorting - Order results by specific fields in ascending or descending order
  • Search - Find records matching specific criteria across multiple fields

Authentication

HMAC Authentication Required

All API requests must use HMAC signature authentication. See the Authentication documentation for detailed instructions on generating signatures.

Important: All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authenticated Request

GET
/api/v1/export/244/tickets
curl -X GET \
  'https://conecto-api.shift4payments.com/api/v1/export/244/tickets?filter[dateTimeFrom]=2018-03-01&filter[dateTimeTo]=2018-03-31' \
  -H 'Content-Type: application/json' \
  -H 'x-access-key: 3cac6f14875e1ed564e8e4f7c4b1916e' \
  -H 'x-signature: b8bc892d56050e4d929be06771222e32e42bc4d5679bb79e6fd3f61f20e15ff5' \
  -H 'x-timestamp: 1530194117'

Pagination

Requesting Pages

You can request specific portions (pages) of results using offset and limit query parameters.

  • Name
    offset
    Description

    Number of items to skip before returning results. Defaults to 0.

  • Name
    limit
    Description

    Maximum number of items to return per page. Check endpoint documentation for maximum values.

Pagination Metadata

Paginated responses include metadata with the total count of items matching your query:

{
  "meta": {
    "count": 27
  },
  "results": [
    // ... paginated items
  ]
}

Example Usage

Retrieve Second Page

Get items 11-20 (skipping first 10, limiting to 10 results)

?offset=10&limit=10

Retrieve First 50 Items

Get the first 50 results (common for initial load)

?limit=50

Sorting

Sort Parameters

Requests that return collections can be sorted using the sortBy query parameter. This parameter accepts either JSON string format or URI-encoded object format.

Sorting Rules

  • Name
    ASC
    Description

    Ascending order - A-Z, Smallest to Largest, Oldest to Newest

  • Name
    DESC
    Description

    Descending order - Z-A, Largest to Smallest, Newest to Oldest

Example Usage

JSON Format

Sort by creation date from newest to oldest:

?sortBy={"createdAt":"DESC"}

Sort by multiple fields:

?sortBy={"status":"ASC","createdAt":"DESC"}

URI-Encoded Format

Alternative syntax for the same sorting:

?sortBy[createdAt]=DESC

Multiple fields:

?sortBy[status]=ASC&sortBy[createdAt]=DESC

Filter Parameters

Requests that return collections can be filtered using the filter query parameter. This parameter accepts either JSON string format or URI-encoded object format.

Date Range Filtering

Filter records by date range using dateTimeFrom and dateTimeTo parameters:

JSON Format

Filter records created in March 2007:

?filter={"dateTimeFrom":"2007-03-01T00:00:00Z","dateTimeTo":"2007-03-31T23:59:59Z"}

URI-Encoded Format

Alternative syntax for the same filter:

?filter[dateTimeFrom]=2007-03-01T00:00:00Z&filter[dateTimeTo]=2007-03-31T23:59:59Z

Field-Specific Filtering

Filter by any supported field. Check endpoint documentation for available filter fields:

?filter={"status":"completed","amount[gte]":1000}

?filter[status]=completed&filter[amount][gte]=1000

Errors

HTTP Status Codes

The Lighthouse API uses conventional HTTP response status codes to indicate success or failure:

  • Name
    2xx - Success
    Description

    Request succeeded. The specific code indicates the type of success (200, 201, 204, etc.)

  • Name
    4xx - Client Error
    Description

    Request failed due to client error, such as missing required parameters, invalid format, or authentication issues

  • Name
    5xx - Server Error
    Description

    Request failed due to a server error. These errors are rare and typically temporary

Common Status Codes

Status CodeDescription
200 - OKEverything worked as expected
400 - Bad RequestThe request was unacceptable, often due to missing required parameter
401 - UnauthorizedInvalid or missing authentication credentials
404 - Not FoundThe requested resource does not exist
429 - Too Many RequestsToo many requests hit the API too quickly (rate limiting)
500 - Internal Server ErrorRequest failed due to a server error

Error Response Format

Error responses include a structured JSON object with status and message details:

Error Response

{
  "error": {
    "status": 400,
    "message": "name_is_required"
  }
}

Best Practices

  • Name
    Use Pagination
    Description

    Always use pagination for endpoints that return collections. This improves performance and reduces memory usage.

  • Name
    Efficient Filtering
    Description

    Apply filters to reduce the dataset on the server side rather than filtering in your application after retrieval.

  • Name
    Appropriate Page Sizes
    Description

    Choose page sizes that balance network efficiency with response time. Typical values range from 20 to 100 items.

  • Name
    Handle Errors Gracefully
    Description

    Implement proper error handling for all HTTP status codes, especially 401 (re-authentication) and 429 (rate limiting).

  • Name
    URI Encoding
    Description

    When using complex filter or sort parameters, ensure proper URI encoding to avoid parsing errors.

  • Name
    Date Formats
    Description

    Use ISO 8601 format for dates (YYYY-MM-DDTHH:mm:ssZ) to ensure consistent parsing across time zones.

Was this page helpful?