Postal DevelopersCatalogue sync
Keep an external system of record and a Postal library in step.
A label, publisher or distributor keeps its own database of works and recordings. Postal holds the audio and the working metadata. This recipe keeps the two aligned in both directions.
Into Postal
- Ingest audio by URL. Put the files somewhere Postal can fetch them
(a signed S3 or R2 URL is fine) and call
POST /tracks/upload/urlwith up to 25 items per request. Passdetailsso ISRC, artist and album land on the first write. - Create composers once. For each writer or publisher, call
POST /composerswith their PRO and IPI. Keep a map from your internal id to the Postalid. - Patch metadata as it changes. Use
PATCH /tracks/detailswhen a title, ISRC or release year changes on your side.
Scopes: create:tracks, update:tracks, create:composer, update:composer,
read:composers, read:composer.
Out of Postal
Attach a webhook to the key and handle:
| Event | What to do |
|---|---|
track.audio_profile_completed | Read BPM, key, duration and tags into your system |
track.updated | Pull the changed details |
shareholder.linked_to_track, shareholder.track_updated | Update split percentages |
composer.updated | Refresh PRO and IPI |
Verify every delivery with the signature recipe, deduplicate on
X-Postal-Event-Id, and re-fetch with the API rather than trusting the
payload for anything you write to a ledger.
Reconcile
Once a day, page through GET /tracks with
fields=id,name,createdAt,cid and diff against your records. Use
GET /tracks/duplicates to catch the same
master uploaded twice under different names.
Notes
- Uploads are asynchronous. A track exists immediately but its audio profile is empty until analysis completes.
- Email is unique per composer within an account. Search before you create.
- Rate limit is 100 requests per minute per IP. Batch uploads and space reconciliation runs accordingly.