URL Decoder API
The information and data accessible via this API contain Proofpoint proprietary, confidential, and/or trade secret information. Sharing or providing the information to another party without Proofpoint's express written consent is prohibited. Please review the updated Terms of Use for Proofpoint APIs. The TAP API Terms of Use can be found online at API Terms of Use | Proofpoint US.
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.