Create or replace a record

PUT 
/records/:collection/:id

Creates the record, or replaces its payload when updated_at_ms is equal to or later than the stored one. An older write changes nothing and answers with the stored record. The payload is a JSON object of at most 64 KB. Needs the Records add-on and the records:write scope.

Request

Responses

200

The stored record, unchanged when the write was older.

Response Headers

X-Request-Id

The id of this request. Quote it when you contact support.

Hometown-Version

The API version that answered: the one the request named, or the version the account is pinned to.

RateLimit-Policy

The per-minute limit of the account, as limit;w=60.

RateLimit

Requests left in the current minute: limit, remaining and reset in seconds.

201

The record, created.

Response Headers

X-Request-Id

The id of this request. Quote it when you contact support.

Hometown-Version

The API version that answered: the one the request named, or the version the account is pinned to.

RateLimit-Policy

The per-minute limit of the account, as limit;w=60.

RateLimit

Requests left in the current minute: limit, remaining and reset in seconds.

default

Every error is a problem details body; code says which.

HTTP	Code	When
400	invalid_request	The request is malformed.
401	api_key_missing	The request has no API key.
401	api_key_invalid	The key does not match any Hometown key.
401	api_key_revoked	The key was revoked and no longer works.
401	api_key_expired	The key was rotated and its 7-day overlap period ended.
403	scope_missing	The key lacks the scope this operation requires, or the operation belongs to the Records add-on, which the account does not have.
403	tenant_suspended	The account is pending activation or suspended, and every key of the account is refused.
403	terms_not_accepted	The account has not accepted the current API Terms and Data Processing Agreement, and the 30 days after they took effect are over.
403	ip_not_allowed	The request came from an IP address outside the allowlist of the key.
403	api_key_paused	The key is paused because its activity looked unlike its usual traffic.
403	test_key_on_live_route	This operation accepts only a live key.
413	payload_too_large	The request body exceeds 30 MB for POST /v1/estimates or 1 MB for any other operation, or one image exceeds 5 MB.
422	validation_failed	A parameter has a value outside its rules.
422	idempotency_key_reused	The Idempotency-Key was already used with a different body within the last 24 hours.
422	content_rejected	The text or an image did not pass content moderation.
422	sandbox_input_on_live	Inputs that start with sandbox: work only with a test key.
422	unsupported_in_region	Hometown does not price this job in the requested region.
422	webhook_url_rejected	Hometown does not deliver to this URL.
422	webhook_endpoint_limit	The environment already has 16 active webhook endpoints, the most it can have.
422	event_not_redeliverable	The event is older than 30 days.
422	records_cap_reached	The environment already keeps 50,000 customers and records, counted together, the most it can keep.
422	billing_profile_incomplete	The billing profile lacks the legal name, address or country that tax calculation requires.
422	pack_unknown	The pack value is not in the catalog.
429	rate_limited	The key exceeded the per-minute limit of the account.
429	daily_quota_reached	The account reached its daily request limit.
429	sandbox_daily_cap_reached	The test keys of an account make up to 200 estimates a day together, sandbox inputs included.
500	internal_error	The request failed inside Hometown.

Response Headers

X-Request-Id

The id of this request. Quote it when you contact support.

Hometown-Version

The API version that answered: the one the request named, or the version the account is pinned to.