Guides

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. When autoScan is enabled, every piece of mail received at this Location 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.
  • 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 of complete. 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 11 days ago