---
title: Set a custom user agent
source: https://docs.newrelic.com/docs/apis/rest-api-v2/basic-functions/set-custom-user-agent
---

To ensure that New Relic correctly identifies API integration publishers, each integration needs a unique custom user agent string.

If you are only using your integration internally, and don't plan on sharing it with anyone outside your organization, you don't need to set a unique custom agent string.

## Prerequisites [#h2_prereqs]

This document assumes you plan to publicly distribute an integration that makes use of any of New Relic's public RESTful APIs. Examples of public distribution include:

-   Publicizing your integration code on Github.
-   Packaging your integration into a plugin, extension, or other package, and distributing it via a directory like [WordPress Plugins](https://wordpress.org/plugins/).
-   Offering an "as a service" integration between your product and New Relic, without actually distributing your integration code, like [Runscope's integration](https://www.runscope.com/docs/api-testing/newrelic#connecting).

## User agents [#h2_user_agents]

When writing applications to work with New Relic's RESTful APIs (referred to as an **integration** in this document), you are creating an HTTP agent to manage information exchange between your application and New Relic. An integration identifies itself by submitting a standard identification string. In HTTP this string is included in the header field **User-Agent**.

When using New Relic's RESTful APIs, set a **User-Agent** header that identifies your integration in API calls. This custom **User-Agent** string allows New Relic to identify the integration that is making requests to New Relic's APIs.

By setting a custom user agent, New Relic can track:

-   Usage statistics for your integration.
-   Potentially buggy or abusive API usage.

## Set a user agent [#h2_setting]

To set a custom user agent, include an agent string in the HTTP header **User-Agent**.

Examples:

| **Language**     | **Example**                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| cURL             | ````sh curl -H 'User-Agent: my-integration/1.2.3' ```  ````             |
| Java (using GET) | ````java get.setHeader("User-Agent", "my-integration/1.2.3"); ```  ```` |
| PHP              | ````php header('User-Agent: my-integration/1.2.3'); ```  ````           |

The minimum user agent string is the integration name and version: `name/version`. You can string together multiple values in a space-separated list. The full syntax is:

```
name/version [(comments)] [name/version [(comments)]] [...]​
```

For the integration name, use a string that clearly and meaningfully identifies your integration.

-   ✗
    Ambiguous name: New Relic Integration
-   ✓
    Clear and meaningful name: SaaS XYZTools Integration with New Relic

For the integration version, use a build ID, commit hash, or other identifier that is updated when you release new integration versions.

Wrap comments in parentheses `()` as a semi-colon separated list;

Helpful comments to include:

-   The publicly-accessible URL of your integration. For instance, a Github URL, or a page in your docs site that describes the integration.
-   Contact information so that New Relic can easily reach the integration publisher.

> #### 💡 TIP
>
> Information from the user agent string will never be shared, nor used by New Relic for any purpose other than discussing the integration with its publisher.

**Set custom user-agent for your integration**

You have an integration with the following identifying information:

-   Name: MetricMeter
-   Version: 3.2
-   URL: meter.me/info
-   Contact: [help@meter.me](mailto:help@meter.me)

    The custom user agent string would be:

    ```
    MetricMeter for New Relic/3.2 (meter.me/info; help​@​meter.me)
    ```

## User agent strings and New Relic [#h2_user_agent_usage]

New Relic captures user agent strings from API calls to identify their source.

Using custom user agent strings for publicly-available integration is a recommended best practice. Depending on your business relationship with New Relic, it may be required. Labeling your integration with a custom user agent string does not affect its interaction with New Relic's APIs.