To use the Perch Partner API, you must authenticate each request with an API key that identifies your application and proves that the request is authorized. The authentication process is simple and stateless — just supply one header with each request.

​
Overview

Every API request must include the following header:
  • X-API-Key - Authenticates your request and identifies your firm
The API key header is required for every request to the Partner API.

​
Steps to obtain and use an API key

1

Contact Perch for API access

Reach out to the Perch team at partnersupport@myperch.io to request API access for your organization. During this process, you’ll need to provide:
  • Your business information and use case
  • The type of integration you’re planning (lead submission, tracking, etc.)
  • Whether you need sandbox or production access (or both)
We recommend starting with sandbox access to test your integration before moving to production.
2

Receive your API key

Our team will provision a long-lived API key tied to your firm record. This key acts as a permanent access token and must be included in the X-API-Key header with every request.You’ll also receive:
  • Your specific API domain (sandbox or production)
  • Documentation specific to your use case
  • Any additional configuration details
Treat your API keys like secrets — keep them out of client-side code and version control. Store them securely in your backend systems only.
3

Configure your environment

Based on your access level, you’ll use one of the following domains:Sandbox Environment:
  • Partner API: api.partner.dit.myperch.io
  • Realtor API: api.realtor.dit.myperch.io
Production Environment:
  • Partner API: api.partner.myperch.io
  • Realtor API: api.realtor.myperch.io
Always test your integration thoroughly in the sandbox environment before switching to production.

​
Sample request

POST /firmMembers/abc12345/leads HTTP/1.1
Host: api.partner.myperch.io
X-API-Key: your-api-key-here
Content-Type: application/json

{
  "email": "client@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890"
}

​
Security and key management

  • API keys are tied to your firm account and all requests are logged internally for security and auditing purposes
  • Store them securely — use environment variables or secure configuration management, never commit them to version control
  • Rotate if compromised — contact partnersupport@myperch.io immediately if you suspect your key has been compromised
  • Backend only — never expose API keys in frontend applications, mobile apps, or any client-side code
  • HTTPS required — all API requests must be made over HTTPS to ensure your API key is transmitted securely

​
Troubleshooting authentication

Common authentication issues and solutions:
Error CodeDescriptionSolution
401 UnauthorizedNo valid API key providedEnsure the X-API-Key header is included and spelled correctly
403 ForbiddenAPI key doesn’t have required permissionsContact support to verify your key’s permissions for the requested resource
429 Too Many RequestsRate limit exceededImplement exponential backoff and respect rate limits
If you experience persistent authentication issues, verify that you’re using the correct domain for your environment (sandbox vs. production) and that your API key matches the environment you’re targeting.

​
Next steps