Valdyr
View as MarkdownOpen in ClaudeOpen in ChatGPT

Licenses

The licenses of the user.

List licenses

GET/licenses

List all licenses.

Query parameters

customerIdarray of string

Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-customer-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

typearray of LicenseType

The type of license to filter by.

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

A list of licenses.

application/json

A list of licenses.

object

itemsarray of Licenserequired
Show child attributes
activatedAtstringdaterequired

The date when the license was activated.

assignedToobject

The entity that a license is assigned to, with the display information for it. A license is always assigned to a subscription.

Show child attributes
subscriptionDisplaystring

Display name for the subscription (typically the phone number)

subscriptionIdstringrequired

The unique identifier for the subscription

typeenum<string>required

The type of assignment

values

  • SUBSCRIPTION
cancelledAtstringdate

The date when the license was canceled (if applicable).

customerobjectrequired

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes
customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

detailsobject

Additional license details specific to certain license types.

Show child attributes
propertyNameany

Any additional properties, passed through as given.

licenseIdstringrequired

The unique identifier for the license.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string
pausedAtstringdate

The date when the license was paused (if applicable).

pendingProductOfferingobject

A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in productOffering until the scheduled date.

Show child attributes
productobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
scheduledAtstringdaterequired

The date when the pending product offering change is scheduled to occur.

pendingStatusobject

A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.

Show child attributes
scheduledAtstringdaterequired

The date when the pending status change is scheduled to occur.

statusenum<string>required

Current stage of the license lifecycle.

  • PENDING: Created but not yet activated
  • ACTIVE: Active and billable; the licensed feature is available
  • PAUSED: Temporarily stopped; the licensed feature is disabled
  • CANCELLED: Permanently terminated
  • BLOCKED: Disabled by the operator, typically for policy or payment reasons

values

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
productOfferingobjectrequired

Essential information about a product offering — what is being sold and at what price — without the full catalog details.

Show child attributes
groupobject

A product group organizes related product offerings.

Show child attributes
imageUrlstringuri

URL to the image representing the product offering.

namestringrequired

The customer-facing name of the product offering, suitable for display in checkout and account views.

priceobjectrequired

The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD.

Show child attributes
productOfferingIdstringrequired

The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.

statusenum<string>required

Current stage of the license lifecycle.

  • PENDING: Created but not yet activated
  • ACTIVE: Active and billable; the licensed feature is available
  • PAUSED: Temporarily stopped; the licensed feature is disabled
  • CANCELLED: Permanently terminated
  • BLOCKED: Disabled by the operator, typically for policy or payment reasons

values

  • PENDING
  • ACTIVE
  • PAUSED
  • CANCELLED
  • BLOCKED
typestringrequired

The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as PBX_USER_LEVEL (a PBX seat for one user), PBX_SOFTPHONE (softphone client), PBX_ROUTE_IVR, PBX_ROUTE_GROUP, PBX_ROUTE_QUEUE, and PBX_ROUTE_VOICEMAIL (call routing features), plus EXTERNAL_PRODUCT for licenses tied to products outside the telecom platform.

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes
nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

messagestringrequired

A human-readable message providing more details about the error.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

hintstring

A hint to help resolve the error.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

messagestringrequired

A human-readable message providing more details about the error.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

spanIdstring

The span within the trace that failed.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

Auth required

Send

  • X-Api-Key + Bearer JWT
GET /licenses
curl https://apiv2.example.com/api/v2/end-user/licenses \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
fetch('https://apiv2.example.com/api/v2/end-user/licenses', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/end-user/licenses",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/licenses"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "activatedAt": "2024-01-15",
      "assignedTo": {
        "subscriptionDisplay": "+1 (555) 123-4567",
        "subscriptionId": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786",
        "type": "SUBSCRIPTION"
      },
      "cancelledAt": "2024-06-30",
      "customer": {
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "John Doe"
      },
      "details": {},
      "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
      "metadata": {
        "propertyName": "string"
      },
      "pausedAt": "2024-03-01",
      "pendingProductOffering": {
        "product": {
          "group": {
            "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
            "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
            "internalDescription": "Core mobile offerings targeting consumer and business segments",
            "name": "Mobile Plans",
            "productOfferingGroupId": "mobile-plans"
          },
          "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
          "name": "Mobile Unlimited",
          "price": {
            "billingCycle": {
              "interval": 1,
              "period": "MONTHLY"
            },
            "bindingContract": {
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "invoicingDescription": "Campaign discount",
                "source": "STANDARD"
              },
              "duration": {
                "unit": "MONTHS",
                "value": 3
              }
            },
            "currency": "USD",
            "currencyOptionsMinor": {
              "propertyName": 1
            },
            "customUpfrontPayment": {
              "billingCycles": 3,
              "discount": {
                "amountMinor": 500,
                "duration": {
                  "unit": "MONTHS",
                  "value": 3
                },
                "invoicingDescription": "Campaign discount",
                "source": "STANDARD"
              }
            },
            "includesTax": false,
            "netPriceMinor": 2999,
            "priceType": "ONE_TIME",
            "standardDiscount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            }
          },
          "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        },
        "scheduledAt": "2024-02-01"
      },
      "pendingStatus": {
        "scheduledAt": "2024-02-01",
        "status": "PENDING"
      },
      "productOffering": {
        "group": {
          "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL",
          "description": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.",
          "internalDescription": "Core mobile offerings targeting consumer and business segments",
          "name": "Mobile Plans",
          "productOfferingGroupId": "mobile-plans"
        },
        "imageUrl": "https://cdn.example.com/images/mobile-basic.png",
        "name": "Mobile Unlimited",
        "price": {
          "billingCycle": {
            "interval": 1,
            "period": "MONTHLY"
          },
          "bindingContract": {
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            },
            "duration": {
              "unit": "MONTHS",
              "value": 3
            }
          },
          "currency": "USD",
          "currencyOptionsMinor": {
            "propertyName": 1
          },
          "customUpfrontPayment": {
            "billingCycles": 3,
            "discount": {
              "amountMinor": 500,
              "duration": {
                "unit": "MONTHS",
                "value": 3
              },
              "invoicingDescription": "Campaign discount",
              "source": "STANDARD"
            }
          },
          "includesTax": false,
          "netPriceMinor": 2999,
          "priceType": "ONE_TIME",
          "standardDiscount": {
            "amountMinor": 500,
            "duration": {
              "unit": "MONTHS",
              "value": 3
            },
            "invoicingDescription": "Campaign discount",
            "source": "STANDARD"
          }
        },
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "status": "PENDING",
      "type": "PBX_USER_LEVEL"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvZmZzZXQiOjEwMH0"
  }
}
{
  "code": "bad_request",
  "details": [
    {
      "code": "invalid_email",
      "message": "Email format is invalid.",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields.",
  "message": "The request body is invalid."
}
{
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header.",
  "message": "Authentication is required to access this resource."
}
{
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions.",
  "message": "You do not have permission to perform this action."
}
{
  "code": "not_found",
  "hint": "Verify the customerId and try again.",
  "message": "The requested customer could not be found."
}
{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}
{
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support.",
  "message": "An unexpected error occurred on the server."
}