UpHunt API

Auto-Apply Setup

How to set up UpHunt auto-apply — invite our business developer into your Upwork agency, then send proposals via API.

UpHunt's auto-apply is built on top of Upwork's Agency Plus feature. We provide you with a dedicated business developer — an Upwork account we manage on your behalf — that you invite into your agency. Every proposal goes out from that business developer, on behalf of your agency and any freelancer in it.

If you've already done this setup, jump to the Quickstart or read How Auto-Apply Works for the under-the-hood pipeline.

What you need

An UpHunt account with auto-apply credits

Sign up at uphunt.io. Every new account comes with a 7-day trial. Paid plans refresh auto-apply credits each billing cycle — see pricing.

An Upwork agency with Agency Plus enabled

Auto-apply requires an Upwork Agency Plus subscription on your side — this is the Upwork feature that lets agency members submit proposals on behalf of the agency. If you don't have an agency yet, create one in Upwork under Settings → My Teams, then upgrade to Agency Plus.

You keep ownership of the agency. Our business developer is just a member of it, like any other person you'd invite.

Connects on your agency

Each Upwork proposal costs Connects. Because proposals are submitted under your agency, Connects are drawn from your agency's balance. Top up under Upwork → Membership & Connects. UpHunt can't buy Connects for you.

The setup flow

Sign up and meet your assigned business developer

After signup, go to the UpHunt Dashboard Auto-Apply → Business Developer page. We provision a dedicated business developer on Upwork for you and show their profile URL.

UpHunt manages the business developer end-to-end — credentials, session health, proposal submission, everything. You only ever interact with it through your agency.

Invite our business developer into your agency

On Upwork, open Settings → My Teams → Members → Invite Member and paste the profile URL shown in the UpHunt Dashboard. Upwork sends the invite to our business developer — we accept it automatically within a few seconds.

Once accepted, our business developer appears as a member of your agency. From now on, every proposal we submit is tagged with your agency's brand.

Agency Plus lets agency members submit proposals on behalf of the agency. That's the feature this entire flow relies on.

Generate an API key

Back in UpHunt, head to Auto-Apply → API & Webhooks and click Generate API Key. Copy the key immediately — we only show it once. See Authentication for how to send it with each request.

Rotate keys by generating a new one and deleting the old — there is no expiration, so treat any leaked key as compromised and rotate right away.

(Optional) Register a webhook

If you plan to apply asynchronously and want push notifications when an application settles, register a webhook URL under the same API & Webhooks tab. We send application.applied and application.failed events with an X-UpHunt-Delivery dedup header. Full details in Webhooks.

Skip this if you're polling GET /status instead — don't do both.

Send your first /apply request

With the API key in hand and our business developer sitting in your agency, fire a request:

cURL
curl -X POST https://uphunt.io/api/auto-apply-v2/apply \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jobId": "~01abc123def456",
    "coverLetter": "Hi, our team has 5+ years of experience with...",
    "proposal": { "hourlyRate": 65, "timeline": "1 to 3 months" }
  }'

You'll get a queueId back in under a second. The actual application happens asynchronously — see How Auto-Apply Works for the full pipeline.

Pick which freelancer submits each proposal

Here's what Upwork's Agency Plus unlocks: UpHunt can submit a proposal on behalf of any freelancer in your agency, not just the business developer. Every /apply call takes a profileId that names which agency member the proposal should be sent as — the client sees that freelancer's name, title, rate, and portfolio.

In practice:

  1. Call GET /freelancers to list every freelancer in your agency and their profile options (default + specializations).
  2. Pick the best fit for the job and grab its profileId.
  3. Pass that profileId to /apply.

If you manage auto-apply through feeds in the UpHunt dashboard, each feed has a freelancer pinned to it — all proposals matched by that feed go out on behalf of that freelancer. Change the pinned freelancer any time; existing proposals in-flight aren't affected.

If you omit profileId on the API call, we fall back to our business developer's default profile.

How credits work

Each auto-apply attempt reserves one credit. The reservation becomes a deduction only when the proposal is actually submitted to Upwork.

StatusMeaning
appliedCredit deducted — proposal reached Upwork
failedCredit refunded — worker exception
not_availableCredit refunded — job was closed before we could apply
not_eligibleCredit refunded — Upwork rejected based on profile fit
not_enough_connectsCredit refunded — agency out of Connects

Only applied costs a credit. Every failure mode releases the reservation automatically.

Common setup pitfalls

  • Invite not accepted — our business developer accepts invites automatically, usually within seconds. If it's been more than a minute, confirm you pasted the correct profile URL from the Dashboard.
  • "Not eligible" on every job — your agency profile is missing required fields (location, skills, tier) or is brand-new with no completed work. Fill out the agency profile on Upwork, then try again.
  • "Not enough connects" — buy Connects on Upwork for your agency. UpHunt has no way to top them up.
  • 403 on every API call — the UpHunt account behind your API key has no active subscription, or the subscription expired. Check Billing in the Dashboard.
  • Freelancers list is empty — our business developer hasn't been invited to your agency yet, or the invite is still pending. Check My Teams → Members on Upwork.

Next steps

Quickstart

One-shot cURL to submit your first proposal.

How Auto-Apply Works

Pipeline, workers, and the full state machine.

Apply endpoint reference

Every field on the /apply request body.

Webhooks

Push-based notifications when an application settles.

Previous

Quickstart

Next

How Auto-Apply Works

On this page