Phone and Email Validation API

Phone number check · score.phone.validation.mnp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

1
2
3
4
5
6
7
8
9
10
11
12
13
14

The token arrives in the Token response header, not in the body. The body carries the user record. Tokens last 24 hours; call auth.login again when one expires.

A successful call here confirms the token is live and the account is funded. Balances are floating-point USD. For batch jobs, audiences.score.price quotes the run before it starts.

phones takes up to 10,000 numbers per request; geo_iso_code is optional. carrier is the network holding the number today, after porting — not the range's original issuer.

accessibility comes back as valid, invalid or unknown. This is the check that says whether a correctly formatted number is actually in use.

score.phone.scoring is the umbrella method. One call returns the comprehensive check (validation, line type and serving network) plus presence on every OTT channel: WhatsApp, Telegram, Facebook and Instagram, with a phone_accessibility score on top. Use it in place of step 03 when you want everything at once.

emails takes 2,000 to 10,000 addresses per request. Full response model at doc.scoremachine.ai.

Real-time

One call, one answer

For records as they arrive: a lead form, a pre-send check, a routing decision.

Batch

Seven calls, runs in the background

For files and whole lists. Upload once, start the job, poll until it finishes.

1. 01
   UploadPOST /upload

   Send the file. Keep the path it returns.

2. 02
   Projectprojects.create

   Or projects.list to reuse an existing one.

3. 03
   Audienceaudiences.create

   Build it from the uploaded path. Run audiences.contacts.preview first to check columns.

4. 04
   Quoteaudiences.score.price

   Price the run for the service_types you plan to use.

5. 05
   Startaudiences.score.start

   Launch the job. It runs in the background.

6. 06
   Pollaudiences.score.status

   Every 2 seconds at most, until status reads active.

7. 07
   Exportaudiences.export

   Download results as CSV or Excel.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

1
2
3
4
5

1
2
3
4
5
6
7
8
9
10
11
12
13

1
2
3
4
5
6
7

Every phone method takes an array of up to 10,000 numbers and an optional geo_iso_code. All but score.phone.validation, .mnp and .ehlr need 2,000 at least. Switching checks means changing one string. Full reference →

Errors come back in the standard JSON-RPC envelope with code, message and optional data. Retry transient failures with backoff. Full method reference, error list and troubleshooting at doc.scoremachine.ai.

1
2
3
4
5
6
7
8
9
10

Errors return HTTP 200 with an error object in place of result. Check for error before reading result.

Codes are shared across related conditions, so log message along with code.

Common causes

In the Token response header. The JSON body carries the user record, not the token. Send it back as Token: <token> on every other call.

Yes. Your account manager issues long-lived keys for server-to-server integrations. Session tokens from auth.login last 24 hours.

There's no separate sandbox. Your $5 free trial runs real checks on the live API.

No SDK is published. The API is plain JSON-RPC 2.0 over HTTPS POST, so any HTTP client works. The curl, Python and Node samples on this page run as written. The Postman collection is available from doc.scoremachine.ai.

No. Poll audiences.score.status no more than every 2 seconds until status reads active, then call audiences.export.

Call audiences.score.price with the audience and the service_types you plan to run. It returns a quote in USD. Check it against balance.get before calling audiences.score.start.

Yes. JSON-RPC and SMPP reach the same methods on the same account.