{"openapi":"3.1.0","info":{"title":"Planet Partner API","version":"1.0.0","description":"Submit leads from your own systems and follow what happens to them.\n\n**Authentication.** `Authorization: Bearer plk_live_…`. Keys carry their\nmode in the value: a `plk_test_` key never touches real data and is\nanswered from fixtures, so an integration can be built and asserted\nagainst stable responses.\n\n**Test scenarios.** In test mode the company name selects the outcome:\na name containing `reject` returns a rejected submission, `review`\nreturns one in review, `duplicate` returns a rejection for an existing\nrelationship, and anything else is accepted.\n\n**Idempotency.** Send `Idempotency-Key` on POST. A retry with the same\nkey replays the original response; the same key with a different body\nanswers 409 rather than creating a second record.\n\n**Deprecation.** Breaking changes get a new path version and the\nprevious one keeps working for at least six months from the\nannouncement. `Sunset` headers carry the date.","contact":{"name":"Planet Partner Support","email":"partner-support@planetlib.com"}},"servers":[{"url":"https://planetlib.com/api/partner-api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Available scopes: submissions:write, submissions:read, leads:read, commissions:read, onboarding:read"}},"schemas":{"Submission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"company_name":{"type":"string"},"zefix_uid":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","in_review","accepted","rejected"]},"stage":{"type":"string"},"rejection_reason_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/onboarding":{"get":{"summary":"How the onboardings you introduced are going","description":"Read-only, and read-only by design: there is no endpoint that hands out a merchant's onboarding link. The stage is coarse on purpose — several internal states collapse into one, so no sequence of responses describes how long a case spent in any particular step.","parameters":[{"name":"submission_id","in":"query","required":false,"schema":{"type":"string"},"description":"Narrow to one of your own submissions."}],"responses":{"200":{"description":"The onboardings for your accepted submissions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"submission_id":{"type":"string"},"company_name":{"type":"string"},"stage":{"type":"string","enum":["preparing","with_merchant","in_review","setting_up","live","closed"]},"target_date":{"type":"string","nullable":true},"waiting_on_merchant":{"type":"boolean"},"first_transaction_at":{"type":"string","nullable":true},"updated_at":{"type":"string"}}}}}}}}},"403":{"description":"The key lacks the onboarding:read scope."}}}},"/submissions":{"post":{"summary":"Submit a lead","description":"Runs the same validation and duplicate detection as the portal form. A consent attestation is required: either the customer has been informed, or you are making the introduction yourself.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company_name","consent_attestation"],"properties":{"company_name":{"type":"string"},"consent_attestation":{"type":"string","enum":["informed","partner_intro"],"description":"`informed`: you have told the customer their details go to Planet. `partner_intro`: you are making the introduction, and we will not contact them before you do."},"zefix_uid":{"type":"string"},"website":{"type":"string"},"contact_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"contact_phone":{"type":"string"},"expected_volume_band":{"type":"string","enum":["under_250k","250k_1m","1m_5m","over_5m"]},"external_ref":{"type":"string","description":"Your own identifier, returned unchanged."},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Validation failed"},"401":{"description":"Missing or invalid key"},"403":{"description":"Key lacks the required scope"},"409":{"description":"Idempotency key reused with a different body"},"429":{"description":"Rate limited"}}},"get":{"summary":"List your submissions","responses":{"200":{"description":"OK"}}}}},"x-webhooks":{"events":["submission.accepted","submission.rejected","lead.stage_changed","commission.accrued","commission.paid","onboarding.stage_changed"],"signature":{"header":"X-Planet-Signature","format":"t=<unix-seconds>,v1=<hex hmac-sha256 of `${t}.${body}`>","note":"Check the timestamp as well as the signature: the timestamp is inside the signed string precisely so a captured request cannot be replayed later."},"retries":{"schedule_minutes":[1,5,30,120,720],"note":"2xx is success. 4xx other than 408 and 429 is treated as a permanent rejection and not retried. An endpoint failing ten deliveries in a row is disabled, and you are told why."}}}