Ordway supports pagination for nested records in Customer API responses. This helps improve response performance when working with customers that have a large number of associated contacts.
Nested contact pagination is supported in applicable Customer API create, retrieve, and update responses.
You can configure pagination behavior using two settings under API Settings:
- Paginate Nested Records: Controls whether Ordway returns nested contacts in pages.
- Include Pagination Statistics: Controls whether the API response includes pagination metadata, such as the current page, page size, offset, and total number of contacts.
When Paginate Nested Records is enabled, Ordway returns up to 50 contacts by default in a Customer API response. You can retrieve additional contacts by specifying the line_page and line_size query parameters.
When pagination is disabled, Ordway attempts to return the entire contacts collection in a single API response. Retrieving a large contacts collection at once can create significant processing load and may result in an HTTP 500 Internal Server Error.
For customers with large contact volumes, keep Paginate Nested Records enabled to retrieve contacts in smaller pages.
Contents
- Overview
- Prerequisites
- Configure Pagination Settings
- Understand Pagination Behavior
- Retrieve Nested Contacts Using API Parameters
- Understand Pagination Statistics
- Update Customers with Nested Contacts
- Frequently Asked Questions
Overview
Customer records can contain a large number of associated contacts. Returning the entire contacts collection in every API response can increase response size and affect processing performance.
The nested record pagination feature allows Ordway to return contacts in smaller sets instead of retrieving the entire collection at once.
You can control this behavior using the following settings:
| Setting | Description |
| Paginate Nested Records | Enables or disables pagination for nested records in Customer API responses. When enabled, Ordway returns up to 50 contacts by default. |
| Include Pagination Statistics | Includes pagination metadata in the API response. The metadata provides information about the current page, page size, offset, and total number of contacts. |
Note: Paginate Nested Records is enabled by default. Include Pagination Statistics is an independent setting and only applies when nested record pagination is enabled.
Prerequisites
Before configuring nested record pagination, ensure that:
- You have access to the Ordway Company Settings.
- You have the required permissions to modify API Settings.
- You have access to the Customer API endpoints.
Configure Pagination Settings
Complete the following steps to configure nested record pagination.
- In Ordway, navigate to Setup > Company Settings.
- Scroll to the API Settings section.
- Locate Paginate Nested Records.
- Enable the toggle to return nested contacts in pages.
- Disable the toggle to return the complete nested contacts collection.
- Locate Include Pagination Statistics.
- Enable the toggle to include pagination metadata in the API response.
- Disable the toggle to exclude pagination metadata.
- Click SAVE to save the Company Settings. The confirmation message “Settings updated successfully” appears.
- The selected settings control how nested contacts are returned in applicable Customer API responses.
Understand Pagination Behavior
The two settings work together to control how Ordway returns nested contacts and pagination metadata.
| Paginate Nested Records | Include Pagination Statistics | API response behavior |
| ON | ON | Returns up to 50 contacts by default, with pagination metadata. |
| ON | OFF | Returns up to 50 contacts by default, without pagination metadata. |
| OFF | Not applicable | Attempts to return the complete contacts collection without pagination. Retrieving a large collection can create significant processing load and may result in an HTTP 500 Internal Server Error. |
Pagination Enabled, Statistics Enabled
When both settings are enabled:
- Ordway returns up to 50 contacts by default.
- You can request additional pages using line_page and line_size.
- The response includes a contacts_pagination object containing pagination information.
Pagination Enabled, Statistics Disabled
When Paginate Nested Records is enabled and Include Pagination Statistics is disabled:
- Ordway still returns nested contacts in pages.
- You can use line_page and line_size to retrieve additional pages.
- The response does not include the contacts_pagination object.
Pagination Disabled
When Paginate Nested Records is disabled:
- Ordway attempts to return the complete nested contacts collection in a single API response.
- The response does not include pagination metadata.
- The line_page and line_size parameters are not used for nested contact pagination.
- Retrieving a large contacts collection can create a significant processing load.
Important: For customers with approximately 50,000 contacts, attempting to return the entire collection can result in an HTTP 500 Internal Server Error because of the processing load. Enable Paginate Nested Records to retrieve contacts in smaller pages.
Retrieve Nested Contacts Using API Parameters
When pagination is enabled, Ordway returns the first 50 contacts by default.
To retrieve a different page or change the number of contacts returned, use the following query parameters:
| Parameter | Description |
| line_page | Specifies the page number to retrieve. |
| line_size | Specifies the number of nested contacts to return per page. |
Example: Retrieve the Default Page
Use the Customer API endpoint without pagination parameters:
| GET {{url}}/api/v1/customers/C-82822 |
Ordway returns the first 50 contacts by default.
Example: Retrieve a Specific Page
To retrieve the third page with 40 contacts per page, use:
| GET {{url}}/api/v1/customers/C-82822?line_page=3&line_size=40 |
Ordway returns up to 40 contacts for the requested page.
You can change the page number and page size to retrieve other portions of the contacts collection.
For example:
| GET {{url}}/api/v1/customers/C-07812?line_page=7&line_size=40 |
This requests page 7 with 40 contacts per page.
Note: The pagination parameters control the nested contacts collection. They do not change the Customer record being requested.
Understand Pagination Statistics
When both Paginate Nested Records and Include Pagination Statistics are enabled, Ordway includes a contacts_pagination object in the Customer API response.
This object provides information about the returned contacts.
Pagination Response Fields
| Field | Description |
| page | Current page number. |
| size | Number of contacts requested per page. |
| offset | Number of contacts skipped before the current page. |
| total | Total number of contacts associated with the Customer. |
Example: Default Pagination Response
When you request a Customer without specifying pagination parameters, Ordway returns the first 50 contacts and includes pagination statistics.
|
{ "contacts_pagination": { "page": 1, "size": 50, "offset": 0, "total": 41002 } } |
In this example:
- page: 1 indicates the first page.
- size: 50 indicates that 50 contacts are returned per page.
- offset: 0 indicates that no contacts were skipped.
- total: 41002 indicates that the Customer has 41,002 contacts.
Example: Pagination Response for a Specific Page
The following example shows the pagination statistics when requesting page 989 with 40 contacts per page.
| GET {{url}}/api/v1/customers/C-82822?line_page=989&line_size=40 |
Response metadata:
|
{ "contacts_pagination": { "page": 989, "size": 40, "offset": 39520, "total": 41002 } } |
In this example, Ordway returns the requested page and reports the corresponding pagination information.
Note: The contacts_pagination object is included only when Include Pagination Statistics is enabled.
Update Customers with Nested Contacts
You can use the Customer API to create or update a Customer along with its associated contacts.
When updating a Customer, Ordway processes the contacts included in the request rather than loading every contact associated with the Customer for the existing-contact lookup.
The request can include:
- Existing contacts with their Contact IDs.
- New contacts without Contact IDs.
- A combination of existing and new contacts.
For existing contacts, include the Contact ID in the request to identify the record to update.
When an existing contact's custom-field value is omitted from an update request, Ordway preserves the existing value.
Use header_only with Contact Updates
The header_only parameter controls the response format. It does not prevent Ordway from processing contact changes included in the request.
Example
|
PUT {{url}}/api/v1/customers/C-00019?header_only=true Content-Type: application/json |
Request body
|
{ "contacts": [ { "id": "<existing-contact-id>", "display_name": "Updated Contact" } ] } |
When you submit contacts in the request:
- Ordway processes the submitted contact changes.
- Existing contacts are updated using their Contact IDs.
- New contacts included without IDs are processed as new contacts.
- The contacts included in the request are returned in the response.
- The response does not return the complete contacts collection.
This allows you to use header_only to reduce the response size without skipping contact processing.
Frequently Asked Questions
| Questions | Answers |
| How many contacts does Ordway return by default when pagination is enabled? | Ordway returns up to 50 contacts by default for an applicable Customer API response. |
| Can I retrieve more than 50 contacts? |
Yes. Use line_page and line_size to request additional pages and specify the number of contacts to return per page. Example: GET {{url}}/api/v1/customers/C-82822?line_page=3&line_size=40 |
| Do I need to enable Include Pagination Statistics to use pagination? | No. You can enable Paginate Nested Records without enabling Include Pagination Statistics. Ordway still paginates the contacts, but the response does not contain pagination metadata. |
| What happens when Include Pagination Statistics is disabled? | Ordway continues to paginate nested contacts, but it does not include the contacts_pagination object in the response. |
| What happens when Paginate Nested Records is disabled? | Ordway attempts to return all associated contacts in a single API response instead of retrieving them in pages. |
| Does header_only prevent contact updates? | No. header_only controls the response format. Contacts included in the request are still processed. When contacts are included in a Customer update request, those submitted contacts are returned in the response rather than the complete contacts collection. |
| Where can I find the total number of contacts? | Enable Include Pagination Statistics along with Paginate Nested Records. The contacts_pagination.total field provides the total number of contacts associated with the Customer. |
| Does pagination change how contacts are created or updated? | No. Pagination changes how nested contacts are returned in API responses. Existing contacts can still be updated, new contacts can still be created, and requests containing both types of contacts continue to be supported. |
| What is the recommended setting for customers with large contact volumes? | Keep Paginate Nested Records enabled. Ordway returns up to 50 contacts by default, and you can retrieve additional pages using line_page and line_size. |
Comments
0 comments
Please sign in to leave a comment.