Skip to main content

​
First Ramp Setup

This guide walks you through setting up your first ramp as a distributor.

​
Prerequisites

  • Docyard account (signed up and verified)
  • Business verification documents ready

​
Step 1: Sign In

curl -X POST https://api.docyard.io/v1/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'
Response: 
{
  "distributor_id": "dist-abc123",
  "api_key": "dk_live_xxxxxxxxxxxx"
}

​
Step 2: Create Your Ramp

A ramp is your upload endpoint. Create one for production use: 
curl -X POST https://api.docyard.io/v1/ramps \
  -H "X-API-Key: dk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Ramp",
    "description": "Main upload endpoint for insurance declarations"
  }'
Response: 
{
  "ramp_id": "ramp-xyz789",
  "name": "Production Ramp",
  "api_key": "dk_live_dist_aaaaaaaa",
  "api_secret": "dk_secret_dist_bbbbbbbb",
  "created_at": "2026-03-15T10:00:00Z"
}
Important: Save your api_key and api_secret securely.

​
Step 3: Create a Development Ramp (Optional)

Create a separate ramp for testing: 
curl -X POST https://api.docyard.io/v1/ramps \
  -H "X-API-Key: dk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Ramp",
    "description": "Testing endpoint"
  }'
Response: 
{
  "ramp_id": "ramp-dev-001",
  "name": "Development Ramp",
  "api_key": "dk_test_dist_aaaaaaaa",
  "api_secret": "dk_test_secret_bbbbbbbb"
}
Note: Test keys use the dk_test_ prefix.

​
Step 4: Verify Your Ramp

Test that your ramp is working: 
curl -X GET https://api.docyard.io/v1/ramps/ramp-xyz789 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb"
Response: 
{
  "ramp_id": "ramp-xyz789",
  "name": "Production Ramp",
  "status": "active",
  "stats": {
    "total_uploads": 0,
    "last_upload_at": null
  }
}

​
Step 5: Create an Artifact Type Template

Before uploading, you need an artifact type template. Here’s a basic insurance declaration template: 
curl -X POST https://api.docyard.io/v1/templates \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Insurance Declaration Page",
    "description": "Standard insurance policy declaration document",
    "locks": [
      {
        "name": "policy_number",
        "data_type": "string",
        "description": "Insurance policy number",
        "validation": {
          "pattern": "^POL-[0-9]{8}$"
        },
        "weight": 20,
        "required": true
      },
      {
        "name": "effective_date",
        "data_type": "date",
        "description": "Date the policy becomes effective",
        "weight": 10,
        "required": true
      },
      {
        "name": "mortgagee_name",
        "data_type": "string",
        "description": "Name of the mortgagee/lender",
        "weight": 5,
        "required": false
      },
      {
        "name": "address",
        "data_type": "string",
        "description": "Property address",
        "weight": 5,
        "required": false
      }
    ]
  }'
Response: 
{
  "template_id": "tmpl-ins-dec-001",
  "status": "pending_approval",
  "message": "Template submitted for admin review. You will be notified once approved."
}

​
Step 6: Wait for Template Approval

Templates require admin review before use. This ensures quality and consistency. You’ll receive an email when your template is approved.

​
Step 7: Upload Your First Artifact

Once approved, upload your first artifact: 
curl -X POST https://api.docyard.io/v1/ramp/artifacts \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl-ins-dec-001",
    "locks": {
      "policy_number": { "value": "POL-12345678" },
      "effective_date": { "value": "2026-03-15" },
      "mortgagee_name": { "value": "FirstCity Bank" }
    },
    "threshold": 20,
    "content": "<base64-encoded-pdf>"
  }'
Response: 
{
  "id": "art-abc123",
  "status": "active",
  "created_at": "2026-03-15T10:30:00Z"
}

​
Managing Multiple Ramps

​
List All Ramps

curl -X GET https://api.docyard.io/v1/ramps \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
Response: 
{
  "ramps": [
    {
      "ramp_id": "ramp-xyz789",
      "name": "Production Ramp",
      "status": "active"
    },
    {
      "ramp_id": "ramp-dev-001",
      "name": "Development Ramp",
      "status": "active"
    }
  ]
}

​
Rotate API Keys

For security, rotate your keys periodically: 
curl -X POST https://api.docyard.io/v1/ramps/ramp-xyz789/rotate-keys \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb"
Response: 
{
  "new_api_key": "dk_live_dist_cccccccc",
  "new_api_secret": "dk_secret_dist_dddddddd",
  "old_key_expires_at": "2026-03-16T10:30:00Z"
}
Important: Update your applications with the new keys before the old key expires.

​
Delete a Ramp

You can delete unused ramps: 
curl -X DELETE https://api.docyard.io/v1/ramps/ramp-dev-001 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb"

​
Best Practices

​
1. Use Separate Ramps Per Environment

Production Ramp:  dk_live_dist_*
Test Ramp:        dk_test_dist_*

​
2. Secure Your API Keys

Never commit keys to version control: 
# .env (add to .gitignore)
DOCYARD_API_KEY=dk_live_dist_aaaaaaaa
DOCYARD_API_SECRET=dk_secret_dist_bbbbbbbb

​
3. Monitor Usage

Check your ramp stats regularly: 
curl -X GET https://api.docyard.io/v1/ramps/ramp-xyz789/stats \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"

​
4. Rotate Keys Regularly

Set a quarterly reminder to rotate API keys.

​
Next Steps