Skip to main content
My preferencesSign out
Proofpoint, Inc.

URL Decoder API

Overview

The URL Decoder API allows users to decode URLs which have been rewritten by TAP to their original, target URL.

API Features

Security

Each request:

  • MUST use SSL.
  • MUST use the HTTP POST method
  • MAY use service credentials to authenticate to the API.
  • MAY use the HTTP Basic Authorization method.

Standard responses

Requests to the endpoints can produce a response with a variety of HTTP status codes. The following table describes the scenarios in which these codes can be produced.

Code Message Scenarios
200 Success At least one record matching the specified criteria was found and returned in the response body. In the case of JSON format, the structure is always returned, even if empty.

400

Bad Request

The request is missing a mandatory request parameter, a parameter contains data which is incorrectly formatted, or the API doesn't have enough information to determine the identity of the customer.

401

Unauthorized

There is no authorization information included in the request, the authorization information is incorrect, or the user is not authorized

429 Too Many Requests The user has made too many requests over the past 24 hours and has been throttled.

500

Internal Server Error

The service has encountered an unexpected situation and is unable to give a better response to the request

Throttle Limits

The number of queries to this endpoint are limited by a simple, rolling 24-hour throttle per service credential. Once exceeded, the API will start returning 429 HTTP status codes until 24 hours past the oldest request has elapsed.

Endpoint

Max Number of Requests

url/decode 1800 per 24 hours


Usage

All endpoints are available on the tap-api-v2.proofpoint.com host. For example, https://tap-api-v2.proofpoint.com/v2/url/decode

/v2/url/decode

Decodes one or more URLs. Available fields in results vary, depending on if the request is authenticated.

Required Parameters

The /v2/url/decode API endpoint takes no GET parameters.

Required Headers

The /v2/url/decode endpoint requires the presence of a Content-Type header with a value of application/json.

Required Request Body

A JSON object containing a urls list must be supplied:

{
    "urls": [
        "https://urldefense.proofpoint.com/v2/url?u=http-3A__links.mkt3337.com_ctt-3Fkn-3D3-26ms-3DMzQ3OTg3MDQS1-26r-3DMzkxNzk3NDkwMDA0S0-26b-3D0-26j-3DMTMwMjA1ODYzNQS2-26mt-3D1-26rt-3D0&d=DwMFaQ&c=Vxt5e0Osvvt2gflwSlsJ5DmPGcPvTRKLJyp031rXjhg&r=MujLDFBJstxoxZI_GKbsW7wxGM7nnIK__qZvVy6j9Wc&m=QJGhloAyfD0UZ6n8r6y9dF-khNKqvRAIWDRU_K65xPI&s=ew-rOtBFjiX1Hgv71XQJ5BEgl9TPaoWRm_Xp9Nuo8bk&e=",
        "https://urldefense.proofpoint.com/v1/url?u=http://www.bouncycastle.org/&k=oIvRg1%2BdGAgOoM1BIlLLqw%3D%3D%0A&r=IKM5u8%2B%2F%2Fi8EBhWOS%2BqGbTqCC%2BrMqWI%2FVfEAEsQO%2F0Y%3D%0A&m=Ww6iaHO73mDQpPQwOwfLfN8WMapqHyvtu8jM8SjqmVQ%3D%0A&s=d3583cfa53dade97025bc6274c6c8951dc29fe0f38830cf8e5a447723b9f1c9a",
        "https://urldefense.com/v3/__https://google.com:443/search?q=a*test&gs=ps__;Kw!-612Flbf0JvQ3kNJkRi5Jg!Ue6tQudNKaShHg93trcdjqDP8se2ySE65jyCIe2K1D_uNjZ1Lnf6YLQERujngZv9UWf66ujQIQ$"
    ]
}

Results

The API endpoint returns a JSON object containing a urls list. Results are in the same order as the input that was supplied. Each object in the list may contain the following fields:

Field Name Description Present in unauthenticated requests? Sample Content
encodedUrl A string, the original, rewritten URL supplied to the endpoint. Yes https://urldefense.proofpoint.com/v2...QLVmleE&e=
decodedUrl A string, the target URL embedded inside the rewritten link. Yes https://media.mnn.com/assets/images/...crop-smart.jpg
success A boolean, indicates whether the URL could successfully be decoded Yes true or false
error A string, indicates what error occurred when attempting to decode input Yes Encoded URL is not a Valid V1, V2, or V3 URL
messageGuid A string, the PPS GUID of the message which originally contained the URL. No rI2j92cEx_-WGPe0PK79iUuy6WLtFeQw
clusterName A string, the name of the PPS cluster which rewrote the message. No acme_inbound_hosted
recipientEmail A string, the email address of the messages' original recipient. No ckent@acme.zz

EXAMPLE OUTPUT

{
    "urls": [{
            "encodedUrl": "https://urldefense.proofpoint.com/v2/url?u=https-3A__media.mnn.com_assets_images_2016_06_jupiter-2Dnasa.jpg.638x0-5Fq80-5Fcrop-2Dsmart.jpg&d=DwMBaQ&c=Vxt5e0Osvvt2gflwSlsJ5DmPGcPvTRKLJyp031rXjhg&r=BTD8MPjq1qSLi0tGKaB5H6aCJZZBjwYkLyorZdRQrnY&m=iKjixvaJuqvmReS78AB0JiActTrR_liSq7lDRjEQ9DE&s=-M8Vz-GV-kqkNVf1BAtv38DdudAHVDAI6_jQQLVmleE&e=",
            "decodedUrl": "https://media.mnn.com/assets/images/2016/06/jupiter-nasa.jpg.638x0_q80_crop-smart.jpg",
            "messageGuid": "rI2j92cEx_-WGPe0PK79iUuy6WLtFeQw",
            "clusterName": "acme_inbound_hosted",
            "recipientEmail": "ckent@acme.zz",
            "success": true
        }, {
            "encodedUrl": "https://urldefense.proofpoint.com/v1/url?u=http://www.bouncycastle.org/&k=oIvRg1%2BdGAgOoM1BIlLLqw%3D%3D%0A&r=IKM5u8%2B%2F%2Fi8EBhWOS%2BqGbTqCC%2BrMqWI%2FVfEAEsQO%2F0Y%3D%0A&m=Ww6iaHO73mDQpPQwOwfLfN8WMapqHyvtu8jM8SjqmVQ%3D%0A&s=d3583cfa53dade97025bc6274c6c8951dc29fe0f38830cf8e5a447723b9f1c9a",
            "decodedUrl": "http://www.bouncycastle.org/",
            "messageGuid": "gnis92cEx_-HYea0PK79iUuy6WLt9kja",
            "clusterName": "acme_inbound_hosted",
            "recipientEmail": "dprince@acme.zz",
            "success": true
        },
        {
            "encodedUrl": "https://urldefense.com/v3/__https://google.com:443/search?q=a*test&gs=ps__;Kw!-612Flbf0JvQ3kNJkRi5Jg!Ue6tQudNKaShHg93trcdjqDP8se2ySE65jyCIe2K1D_uNjZ1Lnf6YLQERujngZv9UWf66ujQIQ$",
            "decodedUrl": "https://google.com:443/search?q=a+test&gs=ps",
            "messageGuid": "fyzs92cFF_-JSUax79iUuy6WLt9lmn",
            "clusterName": "acme_inbound_hosted",
            "recipientEmail": "bwayne@acme.zz",
            "success": true
        }
    ]
}

Example Commands in Curl

The following commands assume that PRINCIPAL and SECRET are defined environment variables. They correspond to the service principal and secret that was created on the Settings page.

curl "https://tap-api-v2.proofpoint.com/v2/url/decode" --user "$PRINCIPAL:$SECRET" -s -H 'Content-Type: application/json' -d '{"urls":["https://urldefense.proofpoint.com/v2/url?u=http-3A__links.mkt3337.com_ctt-3Fkn-3D3-26ms-3DMzQ3OTg3MDQS1-26r-3DMzkxNzk3NDkwMDA0S0-26b-3D0-26j-3DMTMwMjA1ODYzNQS2-26mt-3D1-26rt-3D0&d=DwMFaQ&c=Vxt5e0Osvvt2gflwSlsJ5DmPGcPvTRKLJyp031rXjhg&r=MujLDFBJstxoxZI_GKbsW7wxGM7nnIK__qZvVy6j9Wc&m=QJGhloAyfD0UZ6n8r6y9dF-khNKqvRAIWDRU_K65xPI&s=ew-rOtBFjiX1Hgv71XQJ5BEgl9TPaoWRm_Xp9Nuo8bk&e=","https://urldefense.proofpoint.com/v1/url?u=http://www.bouncycastle.org/&k=oIvRg1%2BdGAgOoM1BIlLLqw%3D%3D%0A&r=IKM5u8%2B%2F%2Fi8EBhWOS%2BqGbTqCC%2BrMqWI%2FVfEAEsQO%2F0Y%3D%0A&m=Ww6iaHO73mDQpPQwOwfLfN8WMapqHyvtu8jM8SjqmVQ%3D%0A&s=d3583cfa53dade97025bc6274c6c8951dc29fe0f38830cf8e5a447723b9f1c9a"]}'

Return full results for the two supplied URLs, using service credentials to authenticate.

curl "https://tap-api-v2.proofpoint.com/v2/url/decode" -s -H 'Content-Type: application/json' -d '{"urls":["https://urldefense.proofpoint.com/v2/url?u=http-3A__links.mkt3337.com_ctt-3Fkn-3D3-26ms-3DMzQ3OTg3MDQS1-26r-3DMzkxNzk3NDkwMDA0S0-26b-3D0-26j-3DMTMwMjA1ODYzNQS2-26mt-3D1-26rt-3D0&d=DwMFaQ&c=Vxt5e0Osvvt2gflwSlsJ5DmPGcPvTRKLJyp031rXjhg&r=MujLDFBJstxoxZI_GKbsW7wxGM7nnIK__qZvVy6j9Wc&m=QJGhloAyfD0UZ6n8r6y9dF-khNKqvRAIWDRU_K65xPI&s=ew-rOtBFjiX1Hgv71XQJ5BEgl9TPaoWRm_Xp9Nuo8bk&e=","https://urldefense.proofpoint.com/v1/url?u=http://www.bouncycastle.org/&k=oIvRg1%2BdGAgOoM1BIlLLqw%3D%3D%0A&r=IKM5u8%2B%2F%2Fi8EBhWOS%2BqGbTqCC%2BrMqWI%2FVfEAEsQO%2F0Y%3D%0A&m=Ww6iaHO73mDQpPQwOwfLfN8WMapqHyvtu8jM8SjqmVQ%3D%0A&s=d3583cfa53dade97025bc6274c6c8951dc29fe0f38830cf8e5a447723b9f1c9a"]}'

Return only the decoded URL for the two supplied URLs, since no service credentials were provided.