Skip to main content

How do I directly integrate with the Herb Postal API?

  • Updated

Prerequisites:

You will need to get the following information from Herb Dashboard:

  • Webhook URL: https://api.herb.report/postal/postcard
  • Integration ID: Go to the “Postcard configuration” tab and copy it from there
     
  • Postal API key:
    • Go to Settings
    • Click on "API key"
    • Click "Create New API key"
    • Add the Key Name and description
    • Select "Postal" under Scopes
    • Click "Create"
    • Copy and save the API key

Guide on direct API Integration:

  • API endpoint: https://api.herb.report/postal/postcard 
  • Headers:
     
    x-api-key: Postal API key you copied from the dashboard
    Content-Type: application/json
  • Input:
     
    Required body:
    {"integration_id": "<INTEGRATIONID>", "email": "<email>"}
    Optional body:
    {"contact_details":
      {
        "zip": <zip>,
        "city": <city>,
        "state": <state>,
        "address": <address>,
        "last_name": <last_name>,
        "first_name": <first_name>,
        "phone_number": <phone_number>,
        "company_name": <company_name>,
        "job_title": <job_title>
      }
    }

    Note: any optional data will overwrite Herb enriched data from email such as username, address, ...
  • Sample:

     
    curl -X POST 'https://api.herb.report/postal/postcard' -H 'x-api-key: <API-KEY>' -H "Content-Type: application/json" -d '{"integration_id": "<INTEGRATIONID>", "email": "<email>", "contact_details": <contact_details>}'
  • Response:
     
    {'request_id': <request_id>, 'status': 'success'}

Check postal request status:

  • API endpoint: https://api.herb.report/postal/postal_status 
  • Headers:
     
    x-api-key: Postal API key you copied from the dashboard
    Content-Type: application/json
  • Input:
     
    {"integration_id": "<INTEGRATIONID>", "request_id": "<request_id>"}
  • Sample:
     
    curl -X POST 'https://api.herb.report/postal/postal_status' -H 'x-api-key: <API_KEY>' -H "Content-Type: application/json" -d '{"integration_id": "<INTEGRATIONID>", "request_id": "<request_id>"}'
  • Response:
     
    {'status': 'success', 'data': <postcard_detail>}

Related articles