Creating Records in Bulk

Meter Entries frequently need to be created in large batches because of the high volume of data. Maybe you are tracking meters for a large number of vehicles in the field, or maybe you're synchronizing activity in regular intervals. These workloads can very easily trigger the Fleetio API's Rate Limits if each record is created one at a time.

Let's look at how to create multiple entries in one request

Step 1: Create a Bulk Job

To create a bulk job, you'll need to issue a POST request to /api/v1/bulk_api_jobs. The JSON body of the request requires three fields:

Field	Description	Values
resource	The type of record to create	fault, group, inventory_journal_entry, location_entry, meter_entry, or vehicle
operation	The action to be taken for the given resource	create or update
records	A list of attributes for the new records	See below

Here is a cURL example for creating Meter Entries in bulk.

info

This example creates two Meter Entries, but you can create up to 100 records via a single HTTP request like this.

$ curl \
--request POST "https://secure.fleetio.com/api/v1/bulk_api_jobs" \
--header "Authorization: Token YOUR_API_KEY" \
--header "Account-Token: YOUR_ACCOUNT_TOKEN" \
--header "Content-Type: application/json" \
--data @- << 'EOF'
{
  "resource": "meter_entry",
  "operation": "create",
  "records": [
    {
      "vehicle_id": 100,
      "date": "2020-01-01",
      "value": 10000
    }, {
      "vehicle_id": 200,
      "date": "2020-01-01",
      "value": 25000
    }
  ]
}
EOF

Each hash in the records list will accept the exact same attribute set that is defined in the non-bulk create endpoint for Meter Entries. Any unexpected attributes will be ignored.

note

There are no restrictions regarding the variety of records included in the array. You can include records for different parent vehicles, different dates, etc, as long as they're all of the same record type.

Once you create a Bulk Job, it will be enqueued and processed in the background. A successful response will look as follows:

{
    "id": "a0e1a07d-2412-47d9-8164-197c1da6a160",
    "completed_at": null,
    "completed_count": 0,
    "created_at": "2020-06-05T09:13:07.119-05:00",
    "failed_count": 0,
    "failed_records": [],
    "operation": "create",
    "resource": "meter_entry",
    "started_at": null,
    "state": "pending",
    "successful_record_ids": [],
    "total_count": 100,
    "updated_at": "2020-06-05T09:13:07.119-05:00"
}

Note that the state is currently pending, and started_at is null. This means that the job has been enqueued, but processing has not been started.

If we need to know when the job has been completed, we will need to another request to check the job's state after some time has passed.

Step 2: Check Job State

Since creating records in bulk can be time consuming, bulk jobs are processed in the background. You will not be notified when a job has completed processing, but you can poll our API to check on the status by using the id returned in the create response.

Once a job is completed, you'll see the following response:

curl \
--request GET \
--header "Authorization: Token YOUR_API_KEY" \
--header "Account-Token: YOUR_ACCOUNT_TOKEN" \
"https://secure.fleetio.com/api/v1/bulk_api_jobs/a0e1a07d-2412-47d9-8164-197c1da6a160"

Below is the response from the above request:

{
    "id": "a0e1a07d-2412-47d9-8164-197c1da6a160",
    "completed_at": "2020-06-05T09:14:00.452-05:00",
    "completed_count": 97,
    "created_at": "2020-06-05T09:13:07.119-05:00",
    "failed_count": 3,
    "failed_records": [
        {
            "index": 1,
            "error_messages": {
                "vehicle": [
                    "can't be blank"
                ]
            }
        },
        /* ... */
    ],
    "operation": "create",
    "resource": "meter_entry",
    "started_at": "2020-06-05T09:13:58.075-05:00",
    "state": "complete",
    "successful_records": [
        {
            "index": 0,
            "id": 52378361
        },
        {
            "index": 1
            "id": 52378362
        },
        /* ... */
    ],
    "total_count": 100,
    "updated_at": "2020-06-05T09:13:07.119-05:00"
}

Notice that state is now complete.

Other fields you'll want to pay attention to:

• started_at: The time the job started.
• completed_at: The time the job completed.
• completed_count: The number of records the job created.
• failed_count: The number of records the job failed to create.
• failed_records: List of records that failed. Includes an index (starting at 0) and an error message. The index corresponds to the position of the record in the request.
• successful_records: An array where each element contains a Fleetio id and an index for each successful record. You can use these in future API requests, for example to retrieve or delete a record.