How to use the Secretary of State API, Updated May 2022
An updated video of how to use the Secretary of State API as of May of 2022.
I use the Nodejs SDK as an example. See (and use it!) here – https://github.com/cobalt-intelligence/cobalt-int-sdk
Documentation – https://cobaltintelligence.stoplight.io/docs/cobalt-intelligence/b3A6MjAxODIxMDU-secretary-of-state-api
Transcript:
Hello there I am Jordan Hanson and I’m from cobalt intelligence today. I want to make a video about how to use the secretary of state API in may of 2022 dun dun duh. Okay. We have another video and post about this. But we’ve updated things since then. It’s probably, I dunno, it’s why not a year old, but six months, at least we made a lot of changes.
So I want to walk through. Some of those changes, this is in JavaScript, but really the important part is the URL you’re going to be building. It’s all a get requests. All the parameters are query parameters. And we have two main queries you can do, which is get business details and get business details by SOS ID.
That’s really the two different ones. And again, that’s just going to change all of this going to change. Whether you pass in this search query, I need to make this bigger. Yup. Oh, that’s like tube or whatever, unless you’re going to pass in the search query. I know right there. So it’s going to be this URL API gateway, that cobalt intelligence.com/v one SLAs search.
And then you’re gonna pass your first query parameter, which almost always will be search query. And that’s going to be your business name. So in the SOS ID one, you’re going to pass an SOS ID there. Okay. So besides that, there are a bunch of different things. You don’t have to worry about. This one, there are a bunch of different parameters you’re going to pass in your always need state.
That’s a required field. You need the state. I need to know what state to query, to find the business data you want to encode your UI, your business. When you send it, I would encode the business name. And the reason for that is a lot of business, same to have ampersands or things like that. Hanson and sons.
And it’s an ampersand. Well, that’s going to break your, your URL. So in Cote d’Ivoire components. So it doesn’t think it’s a separate group. This I am pulling from the SDK, by the way, this is public. Anyone can use it. If they use JavaScript, I would recommend it. That’s what I use. So if you’re using JavaScript, you should use this SDK one day.
Hey, if you want an STK for your language, tell me let’s vote. I want to build other SDKs eventually. And if people tell me what they want, I’d probably be Python. I’ll probably add them Python. C-sharp those are the ones that probably behind me. Okay, next parameter you can get is live data by default. We pull from our database.
Now, I think that’s not where most of our value is. Most of our value comes from live data. Now I should say I should qualify that we pull from our database, but we also, if we don’t have it in the database, we go and get it live. So we’re always going to get your data. If it is. So we’re going to try to get live data or trying to get the database and then we’ll go get live data.
If you pass the live data pram, we’re going to skip the database. We’re going to go right to the source. We’re going to scrape that data right there and pull it back. So that’s the first parameter you can pass in. Simple live camel case data equals true. That’s it. Now you can also pass in a screenshot.
Now screenshot parameter, we support at this moment about 32 states, which means if you pass in this parameter screenshot, true, that’s all lowercase screenshot. Then we’re going to get all, we’re going to take a screenshot of the page and send it back to you. A URL to it, a short-lived URL, where you can go there and you can pull the data back from them.
That’s three buckets. The next parameter, you can do UCC data. We support this and maybe at the moment, nine states that’s adds on. We’re not going to support it in every state because some are crazy and cost money, but UCC that UCC, and then the camel case data right there, pass it in as true. If you pass it in that parameter, we are going to go.
And get the UCC data as well. Rambo search for it. At least if we can find it UCC data, it’s like lean data and most, if you know, you know, if you use it, then it could be. These next three parameters, they are address fields. So if you pass in any of them, a street, a city or a zip, and you just going to pass them in as a query parameter right here like this, then it is going to, we’re going to try to search for just that specific one.
In fact, it’s a restrictive search. It’s an, and so we’re going to try to find by the business name. So if you say, Hey, I’m looking for pizza hut, but I want it to be at this specific zip code. We’re not going to return it anything. And thus, we find it at that. So we’re going to search for that zip code. If we find it, we return it.
So if you have a name that may be questionable and you have an address, I’d recommend using this. Now we use the includes comparison on this, which means if you have a street that says 1, 2, 3 west bank street, suite 100, you could just put fake street in there. That’s fine. You don’t have to put it all.
We’ll use that. And we’ll look for if any street includes fake street. So street. Zip, we do the same kind of thing for all of them. That helps you narrow it down. So those are the basic parameters you can send. Now, all of the states may potentially take longer than 30 seconds and that’s the normal time when we start to do retries.
Meaning that if you should always, you always need to be prepared for this. Occasionally it may come back with a retrial. I should say your API keynotes. You go to your head. It’s like this headers X API key, and this study. That’s what you need. That’s how you get it. So the header is needed to use that right there.
The XAP I can just that API key and you always have a chance to get a reach ID back. For some reason, if it’s taking too long, you need to send it’ll come back, it’ll send every tray B and you take that retry ID and then you send it again at the request. Again, it’s going to look like this. They’re like this.
So you’re still at the past. The screenshot you are. Well, I dunno about that. For sure. You’re going to, it’s going to look at this. The URL is going to be cobalt, intelligence.com, API to gateway dot cobalt, intelligence.com/v one slash search. Then you’re going to pass retry. These are queer parameter, and you can just keep checking back in with that.
Now, do you need, let’s see, what else do you need? I don’t know if you need any of these. There are some of them you need, so it doesn’t hurt to add them as well. I just did it cause I couldn’t remember. I was like, oh, which one thing? That, which ones though. But the most important thing is that requests are, you should be in progress.
You want to check back in and say, Hey, oh yeah, you do need to screenshot one because otherwise we don’t grab it anyway. So we tried to, that’s always a possibility that’s going to come back. And so if it gets it, you just gonna handle it and keep retrying until it finishes. And that’s long polling.
That’s how we do that because some of them can take minutes sadly, but we get them. So I think that’s it. This is how to use the secretary. API and may of 2022, this is current and up to date. We have an extra fields, like I said, and if you have any questions, please post it here and I’ll talk about it or email me, or we have documentation all supposed to documentation in here.
And I keep that up to date. So as soon as we I’d make an update, I update the documentation. It goes up, it gets up to date quickly. Okay. That’s it. Thank you.