Carrier Lookup API Concurrency Queue for Shared Account Slots

A carrier lookup API concurrency queue should coordinate all workers using one account, not let each process guess its own available capacity.

A carrier lookup API concurrency queue should coordinate all workers using one account, not let each process guess its own available capacity. CarrierLookup documents shared in-flight realtime slots and a separate one-multi-request account gate. Put single and synchronous multi requests through an account-wide controller, preserve input order for each multi request, and release a slot only after that request ends. These controls manage simultaneous work; they are not a per-minute quota or a promise about response time.

Model the account, not an individual application worker

Original Carrier Lookup returns original number-allocation context: the originally allocated carrier, underlying carrier, number type and allocation geography. It does not report the current carrier after porting or whether a number can receive a call or message. Realtime here means the request-and-response workflow, not a live network probe. The Original Carrier Lookup API is the relevant product page, and the API documentation should remain the source for current integration details.

When several services share an API account, a per-process semaphore is insufficient. Two web workers, a background import and an analyst tool can each believe the account has spare slots. The documented public rules describe five shared in-flight realtime slots and one multi request per account. A customer-side controller should therefore use a single account-level coordinator, or another mechanism that gives all participating workers one consistent view of outstanding calls. The exact storage or queue technology is a customer implementation choice.

The queue should hold a request envelope with the submitted E.164 identifier or identifiers, request mode, application job reference and the time the team queued it. Those are proposed customer-owned fields, not a claim about CarrierLookup's response schema. Avoid logging full numbers or credentials unless the organization's policy requires and protects them.

Give single and multi calls separate gates

A single lookup accepts one E.164 number. Synchronous multi accepts 1–100 E.164 numbers and returns an ordered result in one response. These are both realtime checks, but the multi route also has an account-wide one-at-a-time restriction. Design two gates: a shared capacity counter for all in-flight realtime requests, and an exclusive gate for a multi request. A multi call must acquire the capacity it needs under the documented account rules and the exclusive multi gate; the implementation should release both together after a completed response or terminal failure.

Do not treat a multi request as an asynchronous bulk file task. The separate Global carrier lookup product accepts TXT or CSV files, prepares identifiers and later produces one CSV. It belongs to a different workflow. The how CarrierLookup works page helps readers distinguish these modes. If the application has a large file job, choose the documented bulk product deliberately rather than pushing a file into the synchronous queue.

The coordinator also needs fairness. A constant stream of single requests should not starve an already queued multi request, while one large import should not indefinitely block small interactive checks. A customer-owned scheduling rule might reserve turns by arrival order or use a limited priority policy. This is a workflow recommendation, not a provider scheduling guarantee.

Handle timeout and worker failure as terminal queue events

A single request and a multi request have documented timeout ceilings in the public API. Use the current API documentation for the exact values and response contract rather than assuming a normal completion time. A client-side timeout can leave uncertainty about whether the server completed the call, so a controller should record that uncertainty separately from a completed carrier result. For synchronous multi, the product documents that a multi timeout fails the whole request without partial results and returns the full amount. Do not manufacture row-level successes from an incomplete response.

Every queue lease needs a release path even if an application worker crashes. The customer's controller can mark the job uncertain, release the local capacity once the worker is known gone, and hand the request to a review or carefully controlled retry policy. Do not automatically flood the service with retries after a network incident. If a retry is chosen, preserve the original application job reference and distinguish the later observation from the earlier uncertain attempt.

A completed lookup can contain empty carrier fields and remain a completed, chargeable result. That is not a timeout and should not consume a retry simply to force a nonempty carrier. Conversely, a rejected input format is not a “no carrier” result. The queue records request state; it does not reinterpret the lookup meaning.

Monitor the queue without inventing a rate limit

Useful customer-side metrics include current in-flight singles, whether a multi request is active, queued age by job class, completed responses, format rejections, timeouts and uncertain transport outcomes. These show whether the application is respecting concurrency and whether users are waiting for a customer-controlled worker. They do not imply a fixed requests-per-minute or daily cap, which the public facts do not state.

Before rollout, test two web workers submitting at once, a queued multi request while singles are active, a worker exit before response, and a timeout. Confirm that no more than one multi request is active for the account and that all acquired local gates are eventually released. Verify that the result is matched to the submitted canonical number and that ordered multi rows are reconciled before updating contact records.

A final operational note should explain that the returned carrier describes original allocation. A fast queue still needs a precise label for original carrier allocation. Store it with a source and check time, keep allocation region and city separate from a person's location, and use other evidence for contactability or identity questions.

FAQ

How should teams coordinate several workers using one CarrierLookup account?

Use an account-wide controller that all workers share, with a shared realtime capacity gate and an exclusive gate for synchronous multi requests.

Does the documented concurrency rule create a per-minute quota?

No. It limits simultaneous in-flight work and does not state a fixed number of requests per minute.

Can a timed-out multi request be partly accepted?

The documented multi timeout fails the whole request without partial results. Keep it as a request-level failure and do not invent successful rows.

Should empty carrier fields trigger an automatic retry?

Not on their own. A completed lookup with empty allocation fields remains a completed result; the team should preserve that outcome accurately.

Learn More

Choose the product information that fits the next step in your workflow.

• View the product documentation →
• Talk to the team →