Platform Prefill
Learn how to add a new Location to your existing Organization and authorize it to receive mail using our platform prefill feature.
Overview
The Platform Prefill feature allows Stable platform partners (resellers) to synchronously create a fully onboarded Location
using the Stable API. This bypasses the standard multi-step onboarding flow and generates a signed USPS Form 1583 automatically at the time of creation.
The United States Postal Service requires Stable to store a signed copy of USPS Form 1583 in order to authorize mail reception at your Location.
This guide walks you through the process of using the platformPrefill
parameter with the POST /v1/locations
endpoint to prefill and create fully onboarded Location
.
You'll learn how to:
- Use the
platformPrefill
parameter to onboard Locations in one step - Understand how to create recipients and understand deduplication behavior.
Why use this?
If you're building a platform integration or need to create many address and want to skip the interactive document upload and signature flow, this feature enables you to provision a Location and start receiving mail immediately—without requiring user interaction.
Prerequisites
Before you begin, you’ll need:
- A Stable API key
- Platform access to the Platform Prefill feature
- Platform Prefill feature is not available to all customers. To request access, contact [email protected] or reach out to your Customer Success Manager
- The required 1583 platform prefill information input, including:
- For business submissions: legal name, business type, and place of registration
- For all submissions: at least one individual recipient
What are the requirements to gain access?
You must be approved for access by our team and sign a document attesting you are authorized to sign the 1583 for the locations you are creating.
Typical use cases include:
- Reseller of Stable's services and have Power of Attorney to sign documents on behalf of your customers.
- A company that needs to create many locations for their own use.
When this feature is enabled for your account, we'll collect information from an authorized company officer in order to fill out the USPS 1583 with prefilled officer information and documents, including a Primary ID , Secondary ID and Verification Photo.
Authentication
All API requests require authentication using your API key in the x-api-key
header:
curl -H "x-api-key: your-api-key" https://api.usestable.com/v1/...
const fetch = require('node-fetch');
const url = 'https://api.usestable.com/v1/locations';
const options = {
headers: {
'x-api-key': 'your-api-key',
'Content-Type': 'application/json',
},
// ...
};
fetch(url, options)
.then(response => console.log('Response:', response.json())
.catch(error => console.error('Error:', error));
import requests
url = 'https://api.usestable.com/v1/...'
headers = {
'x-api-key': 'your-api-key',
'Content-Type': 'application/json',
}
response = requests.get(url, headers=headers)
if response.ok:
print(response.json())
else:
print(f"Error: {response.status_code}, {response.text}")
API Key Security
Keep your API key secure and never expose it in client-side code. All API requests should be made from your backend services.
Process Overview
When using the Platform Prefill feature, creation and onboarding works in a single step.
Step 1: Creating a Location
Start by creating a new Location that will receive mail.
- You'll need to specify a location code from our list of available facilities.
- You should also decide whether to enable
autoScan
. WhenautoScan
is enabled, every piece of mail received at thisLocation
will have its contents opened, scanned, and uploaded, in addition to the outer envelope. - Choose whether to submit a business or individual type Form 1583:
- For business: use
platformPrefill.business
to provide business details. - For individual: omit the
business
object.
- For business: use
- Include recipient information:
platformPrefill.recipients.individual
is required in all cases.platformPrefill.recipients.business
can be included for business submissions.- Business recipients are auto-deduplicated based on
legalBusinessName
.
curl -X POST https://api.usestable.com/v1/locations \
-H "x-api-key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"locationCode": "SFO1",
"autoScan": true,
"platformPrefill": {
"business": {
"legalBusinessName": "Stable",
"placeOfRegistration": "San Franciso, CA",
"businessType": "Software"
},
"recipients": {
"individual":[{
"firstName": "Jack",
"lastName": "Postal"
}]
}
}
}'
const fetch = require('node-fetch');
const url = 'https://api.usestable.com/v1/locations';
const options = {
method: 'POST',
headers: {
'x-api-key': 'your-api-key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
locationCode: 'SFO1',
autoScan: true,
platformPrefill: {
business: {
legalBusinessName: "Stable",
placeOfRegistration: "San Franciso, CA",
businessType: "Software"
},
recipients: {
individual:[{
firstName: "Jack",
lastName: "Postal"
}]
}
}
}),
};
fetch(url, options)
.then(response => console.log('Response:', response.json())
.catch(error => console.error('Error:', error));
import requests
url = 'https://api.usestable.com/v1/locations'
headers = {
'x-api-key': 'your-api-key',
'Content-Type': 'application/json',
}
payload = {
'locationCode': 'SFO1',
'autoScan': True,
'platformPrefill': {
'business': {
'legalBusinessName': 'Stable',
'placeOfRegistration': 'San Franciso, CA',
'businessType': 'Software'
},
'recipients': {
'individual':[{
'firstName': 'Jack',
'lastName': 'Postal'
}]
}
}
}
response = requests.post(url, headers=headers, json=payload)
if response.ok:
print(response.json())
else:
print(f"Error: {response.status_code}, {response.text}")
Response
{
"id": "6510b338-57d9-4aac-8e84-fb047ae42e86",
"status": "active",
"address": {
"line1": "2261 Market Street",
"line2": "#4962",
"city": "San Francisco",
"state": "CA",
"postalCode": "94114"
},
"type": "cmra",
"onboarding": {
"status": "complete"
}
}
Location Status
When created using the Platform Prefill feature, your
Location
will have an onboarding status ofcomplete
. This indicates it's ready to receive mail.
Webhook Notifications
A location.created
webhook event will be dispatched after successful Location
creation.
{
"data": {
"status": "active",
"address": {
"city": "San Francisco",
"line1": "123 Main St",
"line2": "#4962",
"postalCode": "94105",
"state": "CA"
},
"id": "70a3d702-bf1d-4153-8eb2-d3d889aff7f0",
"metadata": null,
"onboarding": {
"status": "complete"
},
"type": "cmra"
},
"eventType": "location.created"
}
Error Handling
Feature not enabled
{
"status": 403,
"message": "Your account does not have access to the platform prefill feature. Please contact support for assistance."
}
Bad input
{
"status": 400,
"message": "At least one individual recipient is required"
}
Updated 20 days ago