Skip to main content

Records

The Records add-on stores two kinds of data for your integration. Customers are the people you price jobs for, with a name, phone, email and address. Records are JSON documents of your own, grouped in collections and named by your own ids. Both live in Hometown, next to the estimates they belong to.

The add-on is paid on its own. Subscribe in the dashboard under Billing, or with POST /v1/billing/checkout and pack: addon_records (see Credits and billing). Without it, /v1/customers and /v1/records answer 403 with the code scope_missing, and detail names the add-on.

Scopes​

ScopeAllows
customers:writeRead, create, change and delete customers.
records:readRead and list records.
records:writeCreate, replace and delete records.

When the add-on is turned on, every key that already carries all the other scopes gains these three. Keys created later carry them too.

Customers​

Create a customer with your own id in external_id:

curl https://api.wfskills.com/v1/customers \
  -H "Authorization: Bearer $HOMETOWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "crm-2291", "name": "Dana Reyes", "phone": "+16015550123", "email": "dana@example.com", "region_code": "US-MS"}'

The answer is the customer, with an id that starts with cus_. external_id is unique in each environment, and a repeat answers 422 validation_failed with param: external_id. To find a customer by your own id, call GET /v1/customers?external_id=crm-2291.

Phone numbers use E.164, like +16015550123. Phone and email are stored encrypted. PATCH /v1/customers/{id} changes only the fields you send, and null clears a field.

Send customer_id when you create an estimate:

curl https://api.wfskills.com/v1/estimates \
  -H "Authorization: Bearer $HOMETOWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Install 100 feet of wood privacy fence"}, "customer_id": "cus_01J9Z6X1M4QK2V7H8T3R5N0BCD"}'

The estimate answers with the same customer_id, and its follow-ups keep it. GET /v1/customers/{id}/estimates lists every estimate linked to the customer, newest first. A customer of the test environment links only to test estimates, and the same holds for live.

DELETE /v1/customers/{id} erases the customer at once, phone and email included. The estimates it was linked to stay, without the link.

Records​

A record is any JSON object of up to 64 KB, stored under a collection and an id you choose. Collection names use lowercase letters, digits and _, and start with a letter. Ids use letters, digits and . _ : @ -, up to 120 characters.

Write a record with PUT, sending the time you changed it in updated_at_ms:

curl -X PUT https://api.wfskills.com/v1/records/jobs/job-1042 \
  -H "Authorization: Bearer $HOMETOWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"title": "Back fence", "status": "scheduled"}, "updated_at_ms": 1760100000000}'

The first write answers 201 and creates the record. A later write answers 200.

The latest write wins​

updated_at_ms is your clock, in milliseconds since the Unix epoch. Hometown keeps the write with the latest value. A write with an older value changes nothing and answers with the record as stored. Two devices that sync in any order end with the same record. Retrying a PUT is always safe, so it takes no Idempotency-Key.

Read a record with GET /v1/records/{collection}/{id}. GET /v1/records/{collection} lists a collection by id in ascending order. Pass the last id of a page in starting_after to get the next one. DELETE erases a record at once.

Limits​

Each environment keeps up to 50,000 customers and records, counted together. Past that, creating one answers 422 records_cap_reached. Changing a customer or a record you already have still works, and deleting frees room.

The add-on is billed by the highest live count of the month. Hometown counts every night, and the dashboard shows the last count. Test data is free.

Export and delete everything​

The dashboard has two buttons for the requests your own customers may make. Export JSON downloads every customer and record of both environments. Phone and email come out readable. Delete all erases them at once, after you type the account's name. Both ask for your password, and Hometown logs both.

If the add-on is turned off, the routes answer 403 at once and the data stays for 30 days. Turning it back on within that time finds everything as it was. After 30 days, the data is erased.

Last updated on