Skip to main content
HomeBlogGuidesYour First Tracking API Request: a Rest Client Walkthrough with Postman and Curl

Your First Tracking API Request: a Rest Client Walkthrough with Postman and Curl

17TRACK

To make your first tracking API request, configure the endpoint, authentication header, and JSON body in a REST client, send the request, and inspect both the HTTP status and the response body. This walkthrough uses 17TRACK’s Tracking API to demonstrate the same workflow in Postman and curl: register a shipment, request its tracking information, and check whether the result is ready for your application to use.

Your First Tracking API Request a Rest Client Walkthrough with

The goal is a small, reproducible integration test—not a production deployment. You will need an API credential and a tracking number you are authorized to process. The commands below use the v2.2 endpoint pattern; confirm the endpoint version and account-specific requirements in the 17TRACK API documentation before running them.

Understand what your first request should accomplish

A shipment tracking integration has two separate concerns: telling the service which shipment to track and retrieving the tracking information associated with that shipment. In the workflow demonstrated here, those are separate requests. Registration does not mean the parcel has already moved, and a successful registration does not guarantee that carrier events will be available immediately.

For your first test, use one shipment rather than a batch. This makes authentication errors, invalid tracking numbers, and response interpretation easier to isolate. Your first useful milestone is not simply “I received HTTP 200.” It is “the API accepted my intended operation, and I can explain the shipment-level result.”

Postman gives you a visual interface for editing requests and inspecting responses. curl makes the same HTTP exchange reproducible from a terminal. Neither changes the API’s authentication rules, shipment data, or processing behavior. Use whichever helps you investigate the request more clearly, then reproduce the working configuration in the other tool.

Prepare your credential, shipment, and request details

Before opening either client, gather the following:

  • An authorized API credential: obtain it through your 17TRACK API account setup. A consumer tracking session is not a substitute for an API credential.
  • A real tracking number: use a shipment you own or have permission to access. A recently active shipment is generally more useful than an invented number when testing actual tracking data.
  • The carrier, if known: keep the carrier name available for diagnosis. If a carrier identifier is required for your case, use the value and field defined in the API documentation rather than guessing.
  • The current request contract: confirm the API version, authentication header, request schema, and any account restrictions.
  • A safe workspace: avoid putting credentials, customer details, or complete tracking responses in public repositories, screenshots, or shared support messages.

The minimal request examples use these settings:

SettingExample configuration
Base URLhttps://api.17track.net/track/v2.2
Registration operationPOST /register
Tracking information operationPOST /gettrackinfo
Authentication header17token: YOUR_API_TOKEN
Body formatContent-Type: application/json, with a JSON array of shipment objects

Keep tracking numbers as strings. Converting one to a numeric type can remove leading zeros or otherwise alter its value. The placeholder YOUR_TRACKING_NUMBER below must be replaced with your actual test shipment; it is not a working sample number.

Make the registration request in Postman

1. Create a small test environment

In Postman, create an environment with three variables: base_url, tracking_token, and tracking_number. Set base_url to the base URL above and enter your credential and shipment number in the other variables. Select that environment before sending the request.

Use Postman’s available secret-handling controls for the token, and check what your workspace shares or synchronizes. Hiding a value in the interface is not a substitute for controlling who can access it. Do not export populated credentials with a collection intended for colleagues or public documentation.

2. Configure the method, URL, and headers

Create an HTTP request, select POST, and enter {{base_url}}/register as the URL. In the Headers tab, add:

17token: {{tracking_token}}
Content-Type: application/json

For this example, the credential belongs in the custom 17token header. Do not replace it with a Bearer token configuration just because another API used that pattern. Also check whether inherited collection settings introduce an unintended Authorization header.

3. Add the JSON body

Open Body, choose raw, and select JSON. Enter:

[
  {
    "number": "{{tracking_number}}"
  }
]

The outer square brackets matter: this request uses an array, even though it contains only one shipment. Use double quotes, remove trailing commas, and keep comments out of the JSON. If the documentation requires additional information for your carrier or shipment, add the documented fields before sending.

4. Send and inspect the result

Click Send. First, check whether you received an HTTP response at all. A DNS failure, TLS error, proxy problem, or timeout is different from a response explaining that the request was invalid. Next, inspect the response body for the operation result and any shipment-level acceptance or rejection information.

Save the request as “Register test shipment.” Record the HTTP status, the API result, and any error message without copying the token. If registration fails, resolve that failure before moving on. Repeatedly submitting an unchanged request makes diagnosis harder and may consume account resources.

Reproduce the request with curl

The following commands use a POSIX-style shell, such as Bash or Zsh. PowerShell and Windows Command Prompt have different quoting and variable rules. In PowerShell, use curl.exe when necessary to invoke the curl executable rather than a shell-specific command alias.

Set the base URL and load your credential into an environment variable through your normal secret-handling workflow:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

An environment variable keeps the credential out of the reusable example, but it is not a complete secret-management system. For local testing, avoid typing a real token into a command that your shell history will retain. For automation, use your platform’s secret store and restrict log output.

Create a file named shipment.json and replace the placeholder with your test tracking number:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Send the registration request:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

This saves the response body to register-response.json and prints the HTTP status separately. The connection and total timeouts are local testing choices, not 17TRACK service guarantees. Open the saved file to inspect the API result; the status line alone is insufficient.

curl can complete a transfer successfully even when the server returns an HTTP error response. Conversely, a transport failure may prevent any usable API response from arriving. When scripting, handle curl’s exit status, the HTTP status, and the application-level result as distinct signals.

Request the shipment’s tracking information

After confirming registration, duplicate the Postman request and change the URL to {{base_url}}/gettrackinfo. Keep the POST method, authentication header, content type, and shipment body. Save it separately so you do not accidentally re-register the shipment when you intend to retrieve data.

The equivalent curl request is:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Do not assume that a newly registered shipment will immediately return a complete event history. Data availability depends on the shipment and the service’s processing. If information is not yet available, follow the documented retrieval and update guidance rather than repeatedly registering the same number or running a tight polling loop.

Read the response in three layers

  1. Transport: did the client connect and receive an HTTP response?
  2. Operation: did the API accept the request, and did the individual shipment succeed?
  3. Shipment information: does the returned data identify the intended parcel, and what does its status or event history actually establish?

Use the official response schema to locate status, carrier, and event fields. Preserve the distinction between a normalized shipment status and the carrier’s original event description. A successful lookup is not evidence of delivery, and missing events are not evidence that a parcel is lost.

When storing timestamps, retain the supplied timezone or offset information. Avoid sorting raw date strings from different formats and assuming they represent a correct chronological sequence. Also distinguish the time your application retrieved a record from the time the shipment event occurred.

Troubleshoot without changing everything at once

  • No response: check the hostname, network access, proxy settings, TLS configuration, and local timeout. Do not disable certificate verification as a routine fix.
  • Authentication failure: confirm that the token is active, the 17token header is present, and the selected Postman environment resolves the variable correctly. Check for accidental whitespace.
  • Invalid request: verify the API version, operation path, POST method, content type, and JSON array structure against the documentation.
  • Shipment rejected: read the shipment-specific error. Check the number and any required carrier information instead of treating every rejection as an authentication problem.
  • No tracking events: confirm registration and the intended shipment identity. Check whether carrier information is needed and whether updates are available before retrying.
  • Postman works but curl fails: compare the resolved URL, actual headers, and body bytes. Shell quoting and unset environment variables are common places for the requests to diverge.

Change one variable per test and keep a short record of the result. If you inspect Postman’s console or use curl’s verbose output, treat the output as sensitive: request headers can expose credentials. Redact secrets and customer information before sharing diagnostics.

Know when the walkthrough is complete

You have completed a meaningful first integration test when both clients send the intended request, registration is understood, retrieval returns an interpretable result, and you can distinguish an API failure from a shipment with no new information. Matching HTTP status codes alone do not establish that the two clients behaved identically.

Before moving the workflow into an application, keep credentials on the server, validate inputs, and use structured error handling. Consult the documented rate limits, batch limits, retry guidance, and update-delivery options for your account. Do not assume registration is safe to retry blindly after a timeout: the server may have processed the request even though your client did not receive the response.

Add tests for an invalid credential, malformed JSON, an invalid shipment number, an already registered shipment, unavailable tracking data, and a network timeout. Each case should lead to a deliberate application outcome rather than an unhandled exception or a misleading customer-facing status.

FAQ

Can I test without a real tracking number?

You can test some request-validation behavior with an invalid value, but that does not verify shipment tracking. To test real events, use an authorized shipment or a documented test fixture if the service provides one. Do not assume arbitrary sample numbers belong to a sandbox.

Why does an HTTP 200 response still contain a failure?

HTTP status and application results describe different layers. A server can successfully receive and process a request while reporting that an individual shipment was rejected. Read the response body and the documented shipment-level result, not just the HTTP status.

Why is POST used to retrieve tracking information?

Use the method specified by the endpoint contract. This retrieval example accepts shipment identifiers in a JSON request body through POST. Changing it to GET because the operation reads data does not preserve the documented request.

Should I put the API token in browser JavaScript?

Do not embed a private API credential in publicly delivered frontend code. Route requests through an authorized backend that protects the credential, validates inputs, and controls which shipment information each user can access.

Do I need both Postman and curl for production?

No. They are useful testing and diagnostic tools. Your production application can use an appropriate HTTP client. Keep a sanitized Postman request or curl command as a reproducible reference, without a live token or unnecessary customer data.

Sources