Build your first query in 5 minutes

No credit card, no waiting. A free key gets you a sandbox with 100 test credits — enough to run every example on this page.

1. 1

   Get your API key

   Go to openappend.com/start, enter your email, and click Create my key. You’ll see your key instantly — it starts with oa_test_. Test keys hit a sandbox and never charge you; when you’re ready you’ll generate a live key (oa_live_) and buy prepaid credits.

   Save it somewhere safe — you’ll use it on every request:

   bashCopy

   export OA_KEY="oa_test_<your_key_here>"
   

2. 2

   Count peopleFREE

   Say you want to know how many homeowners in California are 30–50 years old. Count them first — it’s free.

   POST/v1/people/countFREE

   requestbashCopy

   curl -X POST https://api.openappend.com/v1/people/count \
     -H "Authorization: Bearer $OA_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "filters": {
         "state": "CA",
         "home_owner": true,
         "age": { "gte": 30, "lte": 50 }
       }
     }'
   

   responsejsonCopy

   {
     "data": { "count": 847000 },
     "meta": {
       "credits_used": 0,
       "credits_remaining": 100,
       "request_id": "req_abc123"
     }
   }
   

   No charge — you just qualified an audience of 847,000 people.

3. 3

   Search without revealingFREE

   See the record shape and field names before you spend anything. Contact info stays gated.

   POST/v1/people/searchFREE

   requestbashCopy

   curl -X POST https://api.openappend.com/v1/people/search \
     -H "Authorization: Bearer $OA_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "filters": {
         "state": "CA",
         "home_owner": true,
         "age": { "gte": 30, "lte": 50 }
       },
       "reveal": false,
       "limit": 10
     }'
   

   responsejsonCopy

   {
     "data": [
       {
         "id": "person_xyz123",
         "first_name": "Jane",
         "last_name": "Smith",
         "state": "CA",
         "home_owner": true,
         "age": 38,
         "phones_count": 2,
         "emails_count": 1
       }
       // ... 9 more records
     ],
     "meta": {
       "total": 847000,
       "returned": 10,
       "credits_used": 0,
       "credits_remaining": 100,
       "request_id": "req_def456"
     }
   }
   

4. 4

   Unlock contact info

   Ready for real phone numbers and emails? Flip reveal: true.

   POST/v1/people/search

   requestbashCopy

   curl -X POST https://api.openappend.com/v1/people/search \
     -H "Authorization: Bearer $OA_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "filters": {
         "state": "CA",
         "home_owner": true,
         "age": { "gte": 30, "lte": 50 }
       },
       "reveal": true,
       "limit": 3
     }'
   

   responsejsonCopy

   {
     "data": [
       {
         "id": "person_xyz123",
         "first_name": "Jane",
         "last_name": "Smith",
         "phones": [
           { "number": "+16505551234", "line_type": "mobile", "dnc": false, "rank": 1 },
           { "number": "+16505552345", "line_type": "landline", "dnc": false, "rank": 2 }
         ],
         "emails": ["jane.smith@email.com"]
       }
       // ... 2 more records
     ],
     "meta": {
       "returned": 3,
       "credits_used": 3,
       "credits_remaining": 97,
       "request_id": "req_ghi789"
     }
   }
   

   • Phones are ranked by dialability — phones[0] is your safest bet.
   • Every phone carries a DNC flag: false means safe to call.
   • 3 credits for 3 records — you only pay for what you pull.
5. 5

   Reverse an email to a phone

   Have Jane’s email but need her phone number? Use the shortcut.

   POST/v1/email-to-phone

   requestbashCopy

   curl -X POST https://api.openappend.com/v1/email-to-phone \
     -H "Authorization: Bearer $OA_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "email": "jane.smith@email.com" }'
   

   responsejsonCopy

   {
     "data": {
       "email": "jane.smith@email.com",
       "phones": [
         { "number": "+16505551234", "line_type": "mobile", "dnc": false, "rank": 1 },
         { "number": "+16505552345", "line_type": "landline", "dnc": false, "rank": 2 }
       ]
     },
     "meta": { "credits_used": 1, "credits_remaining": 96, "request_id": "req_jkl012" }
   }
   

   1 credit for a hit. No match, no charge.

Next steps

Common questions