Fetching Records

This section introduces essential features for retrieving records from Cecula API, including response structure, pagination, and search functionality, to help you effectively interact with your data.

Each API response is structured with a data object, containing the requested records, and a meta object that provides context for pagination, such as total records, items per page, and current page number. This structure enables your to navigate through large data collections seamlessly, retrieving manageable chunks of data per request.

📖 Use Cases

See endpoints for fetching Groups and Contacts.

Structure Overview

When fetching records like Contacts or Groups from our API, the JSON response will typically include two main properties: data and meta.

Properties	Description
data	This property contains an array of the requested records. For example, when retrieving contacts, data will include an array of contact objects.
meta	This property provides additional information about the data array, such as pagination details. It includes context like the total number of records, items per page, current page, and total pages, which can be used to manage paginated views effectively.

Sample Response

{
    "data": [
        {
            "uuid": "19e2710e-9d5b-4a97-b246-9780528c4415",
            "first_name": "Akaninyene",
            ...
        },
        {
            "uuid": "c9381744-ed84-4214-9728-72454dd52527",
            "first_name": "Godwin",
            ...
        }
    ],
    "meta": {
        "search": "",
        "total": 2,
        "skipped": 0,
        "perPage": 25,
        "page": 1,
        "pageCount": 1
    }
}

Data Object

The data object contains an array of the records you requested, serving as the main container for the actual dataset returned. For example, when fetching contacts, the data object will hold an array of contact records, each represented as an object with properties like uuid, first_name, phone, and any other relevant fields specific to the dataset.

With each request, the data object presents a consistent and efficient way to access the core dataset, supporting both small queries and paginated results from larger datasets.

Meta Object

This table describes each property in the meta object, including data types, descriptions, and example values to help interpret paginated results effectively.

Property	Data Type	Description	Example Value
search	String	Search phrase that was used to query the records.	customer
total	Integer	The total number of records available in the dataset.	2
skipped	Integer	The number of records that were skipped in the current query, typically based on pagination.	0
perPage	Integer	The number of records returned per page in the current query.	25
page	Integer	The current page number being viewed.	1
pageCount	Integer	The total number of pages available based on the total records and perPage setting.	1

Pagination

Pagination allows you to manage large datasets efficiently by dividing them into smaller, manageable chunks. This feature is particularly valuable when handling extensive data collections, such as contacts, making it easier to retrieve, display, and work with records without overwhelming your server or ours.

The meta object in each paginated response provides essential details, such as total records, current page, items per page, and total pages, helping you to effectively control navigation through data. This guide walks you through understanding and implementing pagination with Cecula API, ensuring seamless integration and efficient data handling.

Paginating Requests

💡 Remember!

Cecula API uses Page-Based Pagination

To paginate your requests, add page and perPage as query parameters to your requests. For example a request for contacts page two could look as follows.

curl --location 'https://app.cecula.com/api/contacts?page=2&perPage=50' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json'

Search

To further refine data retrieval, you may find the Cecula API record search functionality handy. This feature allows you to add search queries directly in the request URL, enabling quick and efficient access to specific records. This feature provides precise data retrieval by returning only the relevant results, which in turn minimizes data transfer and client-side workload.

curl --location 'https://app.cecula.com/api/contacts?search=Akan%20Archibong' \
--header 'Authorization: Bearer test_1tMQT1cfHvEMpjiyWF8skezdmb56krW28Ky6Ctm8c92a7471' \
--header 'Content-Type: application/json'

💡 Note

You can paginate search result by appending the paginate page and perPage queries to the url.