GR API Docs

Oauth 2.0 ​

Register your own application ​

If you want to use an OAuth flow to authorize your application, first register your application here: https://app.getresponse.com/authorizations

You need to provide a name, short description, and redirect URL.

Choosing grant flow ​

Once your application is registered, you can click on it to see your and . They're basically a login and password for your application, so be sure not to share them with anyone.

Next, decide which authentication flow (grant type) you want to use. Here are your options:

  • choose the Authorization Code flow if your application is server-based (you have a server with its own domain and server-side code),
  • choose the Implicit flow if your application is based mostly on JavaScript or client-side code,
  • choose the Client Credential flow if you want to test your application or access your GetResponse account,
  • implement the Refresh Token flow to handle token expiration if you use the Authorization Code flow.

Authorization Code flow ​

First, your application must redirect the resource owner to the following URL:

https://app.getresponse.com/oauth2_authorize.html?response_type=code&client_id=_your_client_id_&state=xyz

The parameter is there for security reasons and should be a random string. When the resource owner grants your application access to the resource, we will redirect the browser to the redirect URL you specified in the application settings and attach the same state as the parameter. Comparing the state parameter value ensures that the redirect was initiated by our system.

Example redirect with authorization code ​

https://myredirecturi.com/cb?code=ed17c498bfe343175cd7684c5b09979f2875b25c&state=xyz

The code parameter is an authorization code that you can exchange for an access token within 10 minutes, after which time it expires.

Exchanging authorization code for the access token ​

Here's an example request to exchange authorization code for the access token:

$  curl -u client_id:client_secret https://api.getresponse.com/v3/token \
        -d "grant_type=authorization_code&code=ed17c498bfe343175cd7684c5b09979f2875b25c"

TIP

Remember to replace and with your OAuth application credentials.

Example response ​

json
  {
      "access_token": "03807cb390319329bdf6c777d4dfae9c0d3b3c35",
      "expires_in": 3600,
      "token_type": "Bearer",
      "scope": null,
      "refresh_token": "170d9f64e781aaa6b3ba036083faba71b2fc4e6c"
  }

Client Credentials flow ​

This flow is suitable for development purposes, especially in cases when you need to quickly access API to create some functionality. You can get the access token with a single request:

Request ​

$  curl -u client_id:client_secret https://api.getresponse.com/v3/token \
        -d 'grant_type=client_credentials'

TIP

Remember to replace and with your OAuth application credentials.

Response ​

json
  {
      "access_token": "e2222af2851a912470ec33c9b4de1ea3a304b7d7",
      "expires_in": 86400,
      "token_type": "Bearer",
      "scope": null
  }

You can also go to https://app.getresponse.com/authorizations, click the action button for your application, and select "Credentials code". This will open a popup with a generated access token. You can then use the access token to authenticate your requests, for example:

$  curl -H "Authorization: Bearer e2222af2851a912470ec33c9b4de1ea3a304b7d7" https://api.getresponse.com/v3/from-fields

Implicit flow ​

First, your application must redirect the resource owner to the following URL:

https://app.getresponse.com/oauth2_authorize.html?response_type=token&client_id=_your_client_id_&redirect_uri=https://myredirecturi.com/cb&state=xyz

When the resource owner grants your application access to the resource, we will redirect the owner to the URL that was specified in the request.

There is no code exchange process because, unlike the Authorization Code flow, the redirect already has the access token in the parameters.

Example redirect ​

https://myredirecturi.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&state=xyz&token_type=bearer&expires_in=3600

Refresh Token flow ​

You need to refresh your access token if you receive this error message as a response to your request:

json
  {
      "httpStatus": 401,
      "code": 1014,
      "codeDescription": "Problem during authentication process, check headers!",
      "message": "The access token provided is expired",
      "moreInfo": "https://apidocs.getresponse.com/en/v3/errors/1014",
      "context": {
          "sentToken": "b8b1e961a7f9fd4cc710d5d955e09c15a364ab71"
      }
  }

If you are using the Authorization Code flow, you need to use the refresh token to issue a new access token/refresh token pair by making the following request:

$  curl -u client_id:client_secret https://api.getresponse.com/v3/token \
       -d 'grant_type=refresh_token&refresh_token=170d9f64e781aaa6b3ba036083faba71b2fc4e6c'

TIP

Remember to replace and with your OAuth application credentials.

The response you'll get will look like this:

json
  {
      "access_token": "890fdsa2f5d7b189fc4e6c4b1d170d9f591238ss",
      "expires_in": 86400,
      "token_type": "Bearer",
      "scope": null,
      "refresh_token": "170d9f64e781aaa6b3ba036083faba71b2fc4e6c"
  }

GetResponse MAX ​

There are some differences when authenticating GetResponse MAX users:

  • the application must redirect to a page in the client's custom domain, for example: https://custom-domain.getresponse360.com/oauth2_authorize.html
  • token requests have to be sent to one of the GetResponse MAX APIv3 endpoints (depending on the client's environment),
  • token requests have to include an X-Domain header,
  • the application has to be registered in a GetResponse MAX account within the same environment.