Making changes

Endpoints that create or change a record share the same rules for request bodies, retries and concurrent edits.

Request body

• A change takes its input as a JSON object in the request body, using the same snake_case field names that the record returns.
• Ids are part of the path. An id in the body never overrides the id in the path.
• A change rejects query parameters it does not accept: an unknown parameter returns 422 naming it, and nothing is changed. A read ignores unknown query parameters.

Idempotency

Send an Idempotency-Key header with a change to make it safe to retry.

The key is required to create a booking request, an extension request, a review, a document, an off-platform booking, a busy block, the calendar feed, a mix, a SoundCloud import, a post, a live event, a widget domain, a PayLink, a conversation, a message, an upload (in one request or in parts) and an import from a URL.

📘

Action links

Creating an action link takes no Idempotency-Key; a key that is sent is ignored. The response contains a secret, and requesting the same link again replaces the previous one.

Uploads

An upload sent with an Idempotency-Key (POST /me/files and each part of a multipart upload) also requires the SHA-256 of the bytes as the sha256 query parameter (64 hexadecimal characters). DJfindr verifies the hash against the bytes it receives. A missing or mismatched hash returns 422 on sha256, and nothing is stored. The same key with a different file returns 409.

Concurrent edits

Send the updated_at value you read as expected_updated_at in the body. If the record changed since you read it, the request returns 412 and nothing is changed.

Withdrawing a booking request

POST /me/bookings/proposals/{id}/withdraw drops a booking before any payment is made. It always requires expected_updated_at; without it, the request returns 422.

A paid booking is cancelled on DJfindr, where the person sees what is refunded and what the DJ keeps. Create a cancellation link to send the person there.

Sometimes a paid booking can't be dropped or canceled online at all for a while. The booking's actions then leave out withdraw, and on the client's side withdraw_blocked is set: { "reason": "contact_support", "message": "..." }. Show its message as it is in place of a cancel option, with a way to contact DJfindr support. Creating a cancellation link meanwhile returns 409 with code: "withdraw_on_hold". withdraw_blocked is null on the DJ's side and whenever nothing stops the booking from being withdrawn.

Validating a booking request

POST /me/bookings/requests?dry_run=true, sent with the request's body, runs every check the request runs and creates and sends nothing: the client's account, the DJ, the date and time, the DJ's availability, and any request already open for the same event.

A dry run requires no Idempotency-Key. It returns 200 with the request as it would be created and a list of warnings:

When a check fails, the dry run returns the same error the request would return, for example 403 with code: "terms_required". A note that passes a dry run can still be refused when the request is sent (422 with code: "note_blocked").

dry_run is accepted only by POST /me/bookings/requests. Any other change returns 422 for it.