Prepare an external TestFlight build for beta review: confirm processing, add what's-new notes and beta app review details, submit, and poll review state

Documented steps

1. Poll for a processed build: GET https://api.appstoreconnect.apple.com/v1/builds?filter[app]=<APP_ID>&filter[processingState]=VALID&sort=-uploadedDate. Supported filters include filter[app], filter[processingState] and filter[version].
2. processingState values are PROCESSING, FAILED, INVALID, VALID. Poll every 30-60s while PROCESSING; FAILED and INVALID are terminal and require a new upload.
3. Note each Build also carries expirationDate and an expired boolean.
4. Add tester-facing release notes: POST /v1/betaBuildLocalizations with {"data":{"type":"betaBuildLocalizations","attributes":{"locale":"en-US","whatsNew":"Fixed crash on launch; improved sync speed."},"relationships":{"build":{"data":{"type":"builds","id":"<BUILD_ID>"}}}}}. locale is required; whatsNew is optional in the schema but is the field testers actually read.
5. If a localization already exists for that build+locale, PATCH /v1/betaBuildLocalizations/{id} instead — a duplicate POST conflicts.
6. Beta App Review contact and demo details are PER APP, not per build. Fetch the resource id with GET /v1/apps/{id}/betaAppReviewDetail.
7. Update it: PATCH /v1/betaAppReviewDetails/{id} with {"data":{"type":"betaAppReviewDetails","id":"<DETAIL_ID>","attributes":{"contactEmail":"dev@example.com","contactFirstName":"Ada","contactLastName":"Lovelace","contactPhone":"+15555550123","demoAccountName":"demo@example.com","demoAccountPassword":"S3cret!","demoAccountRequired":true,"notes":"Use the demo account to reach the paywall."}}}
8. Ensure every betaAppLocalizations record has a description filled in — Apple's endpoint documentation states this is a prerequisite for beta review submission.
9. Submit for beta review: POST /v1/betaAppReviewSubmissions with {"data":{"type":"betaAppReviewSubmissions","relationships":{"build":{"data":{"type":"builds","id":"<BUILD_ID>"}}}}}. The build relationship is required; success is 201.
10. Poll GET /v1/builds/{id}/betaAppReviewSubmission or GET /v1/betaAppReviewSubmissions/{id} and read attributes.betaReviewState. The enum is WAITING_FOR_REVIEW, IN_REVIEW, REJECTED, APPROVED.
11. Once APPROVED, the build is installable by any external beta groups it is assigned to, until it expires.
12. Official docs: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-betaappreviewsubmissions | https://developer.apple.com/documentation/appstoreconnectapi/betareviewstate | https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-betaappreviewdetails-_id_ | https://developer.apple.com/documentation/appstoreconnectapi/get-v1-builds