Skip to content
UpSmith Help Center home

Modernize

Modernize leads go cold fast — the homeowner is shopping, and they're talking to whoever answers first. Connecting Modernize to UpSmith means your agent texts every lead the moment it arrives, at 11pm on a Sunday as readily as Tuesday morning.

The setup is split across two companies, and that's the part worth planning for. UpSmith gives you an address and a key in about a minute. Somebody at Modernize then has to point your lead delivery at that address and match up their field names with ours. That second half isn't something you can do from inside UpSmith, so start the conversation with your Modernize rep before you connect rather than after.

Two things to know first

  • Your API key is shown exactly once. The screen says so: "This API key will not be shown again. Copy and store it now." That's literal — we keep only a fingerprint. Lose it and your only option is to generate a new one and give Modernize the replacement.

  • Nothing arrives until you press Activate. And until you do, anything Modernize sends is accepted and discarded — with no error on their end. More on that below, because it's the one that catches people.

Connecting it

  1. Go to Integrations and click Connect on the Modernize tile.

  2. A window headed Modernize credentials shows your Webhook URL and API key. Copy both somewhere safe before you close it.

  3. Send them to your Modernize contact along with the field mapping below, and wait for them to confirm delivery is pointed at you.

  4. Come back and click Activate.

You can reopen the webhook URL any time under Show Connection Details — it's only the key that's one-time.

What to hand your Modernize rep

Three things, and the third is where the work is:

  • The webhook URL from your card, exactly as shown. Don't retype it — copy it.

  • The API key, sent as a header named x-api-key on every request.

  • The field mapping. Modernize's own field names won't match ours, so someone has to line them up. The names we expect are below.

One field is genuinely required:

  • external_id — Modernize's own unique id for the lead. We use it to avoid creating the same lead twice, so it has to be stable and unique. Without it the request is rejected.

Everything else is optional, but two of them decide whether the integration is worth having:

  • phone — your agent works over text. A lead with no number is recorded and nobody hears from us. Full international form (+15125550142) is safest.

  • message — whatever the homeowner actually said about the job. This goes straight into your agent's opening text, so it's the difference between a message that references their no-cool call and one that doesn't. If Modernize sends the detail under a different name, details, notes, description and additional_details all work too and are read in that order.

Worth mapping if Modernize has them: name (or first_name and last_name), email, address, city, state, zip_code, and marketing tags like campaign_name or ad_name.

Extra fields are kept. Anything Modernize sends that isn't on this list is stored with the lead and handed to your agent as context, so there's no harm in passing through more than you think you need. Two special ones: lead_source records a sub-source so you can separate Modernize's own lead types later, and brand_name sets the business name your agent uses on that specific lead — useful if you run more than one brand.

If Activate won't let you

The card tells you why:

  • "Lead Settings must be configured before Modernize can go live." You have no agent set up to answer new leads. There's an Open Lead Settings button right there — sort that and the blocker clears.

  • "The API key is missing. Rotate the key before activating the connection." Use Rotate key, then send Modernize the new one.

  • Anything about a missing organization slug is ours to fix — email support@upsmith.com.

The one that catches everyone

A lead sent to a connection that isn't active is accepted and thrown away — and Modernize is told it succeeded. Same if the URL has a typo in it, or if you've paused the connection. There's no error, no bounce, nothing for anyone to notice.

That's deliberate — it stops people probing for valid addresses — but it means Modernize reporting successful delivery is not proof a lead reached you. Two practical consequences:

  • Don't have Modernize switch delivery on before you've pressed Activate. Anything sent in the gap is gone, and it can't be replayed.

  • If you pause the connection, ask Modernize to stop sending too. Pausing doesn't queue leads for later — it drops them.

Checking it works

  • The card shows Last webhook received. Before anything arrives it reads "Waiting for first lead...". A timestamp there means something reached us.

  • Then look in Conversations, filtered to the Modernize source.

  • Check both on the first live lead, not the hundredth. A timestamp with no conversation usually means the payload was rejected — almost always a missing unique id.

  • There's no delivery log. We don't keep a viewable record of individual requests, and there's no replay. If a lead is missing, Modernize's own delivery reporting is one half of the picture and that timestamp is the other. Send us the time and the customer's phone number and we'll look from our side.

Pausing and rotating

  • Pause stops leads being accepted — and, as above, quietly discards anything that arrives. Resume starts it again.

  • Rotate key issues a new key and kills the old one immediately, with no confirmation step. Delivery breaks until Modernize has the replacement, so do it when you can reach someone there. It's also the fix for a connection stuck showing Needs attention — rotating clears the error.

  • There's no delete. You can pause it and you can rotate the key, but the connection can't be removed. Pausing is the off switch.

  • Renaming your business won't break it. The webhook address stays put.

Troubleshooting

Modernize says leads are delivering and nothing is in UpSmith. In order: is the connection Active rather than pending or paused; does the URL Modernize has match the one on your card character for character; and is Last webhook received updating. If the timestamp is moving but no conversations appear, the payload is being rejected — check the unique id is mapped.

Modernize reports an authentication failure. The key is wrong or has been rotated. Generate a fresh one with Rotate key and send it over.

Leads arrive but nobody texts them. Either no phone number is coming through, or your lead-response campaign isn't running. Open one of the leads and check whether a number is on it.

Your agent's opening message is vague. The homeowner's description isn't being mapped. Ask Modernize to send it as message — it's the single field that most changes how the first text reads.

You're seeing two leads for one homeowner. The sub-source label is part of how we spot duplicates, so if Modernize maps lead_source from something that varies, the same lead can come through twice. A fixed value avoids it.

You want to test before going live. There's no sandbox — anything sent is a real lead that will get a real text. Use a phone number you control, and expect it to text you.

Common questions

Who sets this up at Modernize — me or UpSmith? You, with your Modernize rep. We don't have access to your Modernize account, so we can't point your delivery at us on your behalf. Send us the details if you get stuck and we'll help you work out what to ask them for.

Do I need UpSmith to switch this on? No. Connecting and activating are yours to do.

Can I connect two Modernize accounts? One connection per UpSmith account. If Modernize sends you several lead types, have them all use the same URL and separate them with the sub-source field.

Will my agent know it's a Modernize lead? Yes — conversations are tagged with the Modernize source and you can filter the inbox by it.

What if a lead arrives while we're closed? Your agent replies whenever it's set to reply; the connection itself doesn't sleep. Outreach timing is set on the agent, not here.

Can I take over a conversation? Yes, exactly as with any other lead — open it and click Take over.

Where to go next