canonical: https://jentic.com/apis/n2p.io/n2p

# N2p net2phone API

The net2phone API places outbound calls from a net2phone user or device, returns call data records for the current user or any user on the account, and manages webhook subscriptions for call, CDR, and recording events. It also returns the authenticated user, the account, and the list of users. A call takes a to value as an E.164 number, extension, or SIP address and an optional from, whose accepted form depends on the account generation. Webhook subscriptions post to a post_uri you supply and expire after expires_in seconds.

## For AI agents

Place click-to-call phone calls from a net2phone user, pull call data records per user, and subscribe a URL to call, CDR, and recording events.

## Scope

Does not send SMS, manage phone numbers, or download call recordings. Use for net2phone click-to-call, call data records, and event webhooks only.

## Capabilities

- Place an outbound call to an E.164 number, extension, or SIP address from a user, with optional auto_answer on Gen V accounts
- Pull call data records for the current user, a specific user by userId, or all users on the account
- Subscribe a post_uri to calls, cdrs, and recordings events for one user or all users, with an expires_in lifetime
- Check or delete a webhook subscription by subscriptionId
- Look up the authenticated user, the account, and the account's users

## Use cases

### Agent click-to-call through Jentic

A developer's sales agent, connected through Jentic, places a call when a lead asks to be phoned back. It calls the place-call operation with the lead's number in E.164 format as to, and the rep's user as from, so the call starts from the rep's own net2phone line without anyone dialling by hand.

Example prompt: Call POST /calls/ with to='+14155550123' and from set to the authenticated user's id from GET `/users/current`/

### Call activity reporting

A manager wants a summary of the team's call activity. An agent pulls call data records for each user from the per-user CDR endpoint, reads start_time, end_time, duration, call_type, and the from and to legs, and builds a per-rep report. On Gen V accounts the all-users CDR listing returns records for everyone in one call.

Example prompt: Call GET /users/ to list users, then GET `/cdrs/users/{userId}`/ for each one and total the call count per user

### Real-time call and recording events

A CRM integration needs to log calls as they happen. A webhook subscription with calls, cdrs, or recordings set to true posts each event to your post_uri, scoped to one user or all users. Subscriptions expire after expires_in seconds, up to 604800, so the integration checks and renews them on a schedule.

Example prompt: Call POST /subscriptions/ with post_uri='https://hooks.example.com/n2p', calls=true, cdrs=true, and expires_in=604800, then GET `/subscriptions/{subscriptionId}`/ to confirm it

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/calls/` | Place a call |
| GET | `/cdrs/users/current/` | Current user CDRs |
| GET | `/cdrs/users/{userId}/` | User CDRs by ID |
| POST | `/subscriptions/` | Create a webhook subscription |
| DELETE | `/subscriptions/{subscriptionId}/` | Delete a webhook subscription |
| GET | `/users/` | List users on the account |

## Key resources

- **Calls** — Outbound calls placed from a user or device to a number, extension, or SIP address
- **CDRs** — Call data records for the current user, a given user, or all users
- **Subscriptions** — Webhook subscriptions for call, CDR, and recording events
- **Users and accounts** — The authenticated user, the account, and its user list

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 43 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 72 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 24 / 100
  - Agent Usability: 94 / 100
  - Security: 30 / 100
  - AI Discoverability: 46 / 100
- **View full report:** https://jentic.com/apis/n2p.io/n2p/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring net2phone by hand means running the OAuth password flow against its token URL, refreshing tokens, sending the versioned media type the API expects, and working out which from format your account generation takes. Through Jentic you install once, import net2phone from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** net2phone puts the user id in the URL path of the per-user CDR and user endpoints, so a rule can pin your agent to specific users' records. You choose the operations it may call, so actions like placing calls or deleting a webhook subscription are not included unless you add them.
- **Credential handling:** Your net2phone credentials and access token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'place a phone call' or 'list my call records', and Jentic returns the matching net2phone operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **RingCentral API** — Cloud phone system with calling, SMS, call logs, and meetings
- **Aircall Public API** — Call center phone system with calls, numbers, users, and webhooks
- **Dialpad API** — Business calling with call logs, contacts, and AI call summaries

## FAQ

### What authentication does the net2phone API use?

Per its OpenAPI spec, the net2phone API uses OAuth 2.0 with the password flow: you exchange your net2phone credentials for an access token at the `/oauth/token`/ endpoint on api.n2p.io and send it with each call. Through Jentic, the credentials and token are stored once by your own Jentic One instance and injected at call time.

### What can I put in the to and from fields when placing a call?

POST /calls/ requires to, which can be a phone number, an extension, or a SIP address; E.164 is recommended for numbers. The from field depends on account generation: Gen P and Gen V take the authenticated user id, Gen U and Gen X take the user's phone number or extension, and Gen V also accepts a SIP user.

### What are the rate limits for the net2phone API?

The spec documents an x-RateLimit-Limit response header per endpoint, with values such as 5/second, 15/minute on the user CDR listing, and some endpoints document 1/second limits. Exceeding a limit returns HTTP 429.

### How long does a net2phone webhook subscription last?

Subscriptions expire after expires_in seconds, which defaults to 7200 and can be set up to 604800. Set calls, cdrs, or recordings to true to choose event types, and leave user at its default of * to cover all users. GET `/subscriptions/{subscriptionId}`/ verifies a subscription, and DELETE removes it.

### How do I place a call through net2phone with Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import the net2phone API from the API Directory, and store your net2phone credentials once. Your agent searches for 'place a phone call', gets the call operation with its input schema, and calls POST /calls/ with a to number. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the net2phone API?

Yes. For a reporting agent, write a rule that allows only GET `/cdrs/users/{userId}`/ for the user ids it should read, so it can pull call records for those people but cannot place calls or change webhook subscriptions. Add POST /calls/ only for an agent that should dial out.