Introduction aux API de SAM.gov

SAM.gov met à disposition des API publiques pour accéder directement aux données des entités fédérales, aux attributions de contrats, aux exclusions, aux opportunités de marchés et aux exports de données en masse. Elles permettent d'intégrer facilement ces flux officiels dans vos plateformes d'analyse, outils de conformité ou systèmes de veille sur les marchés publics.

Notes importantes :

• La plupart des API nécessitent une clé API publique obtenue à partir de votre compte SAM.gov (page Account Details).
• Les limites de requêtes varient selon le type de compte : les utilisateurs non fédéraux sans rôle spécifique sont limités à 10 requêtes/jour ; les utilisateurs disposant de rôles ou de comptes système peuvent atteindre 1 000 à 10 000 requêtes/jour.
• Certaines données peuvent inclure des informations de Dun & Bradstreet (D&B) soumises à des restrictions d'utilisation.
• Pour les prototypes, utilisez toujours des données publiques et respectez les conditions d'utilisation de la GSA.

1. API SAM.gov Entity Management (Gestion des entités)

Documentation officielle : https://open.gsa.gov/api/entity-api/

Description : Permet de récupérer les informations publiques d'enregistrement des entités, notamment l'UEI, la raison sociale (legal business name), le statut d'enregistrement, le statut de l'UEI, les dates de création/expiration, l'indicateur d'affichage public, etc. Prend en charge les données Publices, FOUO et Sensibles en fonction des autorisations de votre compte.

Point de terminaison principal : GET https://api.sam.gov/entity-information/v3/entities (version v4 également disponible)

Paramètres de requête clés

• api_key : Requis – Votre clé API publique
• ueiSAM : Identifiant unique de l'entité (un seul identifiant de 12 caractères ou jusqu'à 100 valeurs)
• cageCode : Code CAGE à 5 caractères (unique ou jusqu'à 100 valeurs)
• samRegistered : Yes / No (Oui / Non, valeur par défaut : Yes)
• registrationStatus : ID Assigned, Active, Expired, etc.
• ueiStatus : Active, Inactive, etc.
• legalBusinessName, dbaName : Recherche par nom commercial partiel ou complet
• physicalAddressCity, physicalAddressStateCode, physicalAddressCountryCode, physicalAddressZipCode
• Filtres de date (date unique ou plage [MM/JJ/AAAA,MM/JJ/AAAA]) : registrationDate, activationDate, updateDate, registrationExpirationDate, ueiCreationDate, ueiExpirationDate
• publicDisplayFlag : Y / N
• includeSections : entityRegistration, entityOverview, entityGeneralInformation, etc.
• page, size : Pagination
• q : Recherche en texte libre (prend en charge les opérateurs avancés)

Exemple cURL

curl -X GET "https://api.sam.gov/entity-information/v3/entities?api_key=VOTRE_CLE_API&samRegistered=No&includeSections=entityRegistration&size=10" 

2. API SAM.gov Contract Awards (Attributions de contrats)

Documentation officielle : https://open.gsa.gov/api/contract-awards/

Description : Fournit des enregistrements détaillés sur les attributions de contrats fédéraux (Awards & IDVs), y compris les informations sur l'attributaire, les montants engagés (obligated dollars), l'agence attributrice, les codes NAICS/PSC, les détails de la mise en concurrence, etc. Prend en charge les données révélées (Revealed) et non révélées (Unrevealed).

Point de terminaison principal : GET https://api.sam.gov/contract-awards/v1/search

Paramètres de requête clés

• api_key : Requis
• limit : Maximum 100 enregistrements par page (par défaut 10)
• offset : Pagination
• uei / awardeeUniqueEntityId : UEI de l'attributaire (jusqu'à 100 valeurs)
• awardeeCageCode : Code CAGE (jusqu'à 100 valeurs)
• dollarsObligated, totalDollarsObligated : Valeur unique ou plage [min,max]
• Paramètres de date (unique ou plage [MM/JJ/AAAA,MM/JJ/AAAA]) : lastModifiedDate, dateSigned, approvedDate, createdDate, closedDate, periodOfPerformanceStartDate, etc.
• naicsCode, productOrServiceCode : Codes NAICS & PSC (jusqu'à 100 valeurs)
• contractingDepartmentCode, contractingSubtierCode, contractingOfficeCode
• piid, modificationNumber, solicitationID
• piidAggregation=yes (nécessite le paramètre piid)
• deletedStatus=yes
• includeSections : contractId, coreData, awardDetails, awardeeData, nasaSpecific
• q : Recherche en texte libre
• format : csv / json (pour l'extraction de masse asynchrone) et plus encore...

Exemple cURL

curl -X GET "https://api.sam.gov/contract-awards/v1/search?api_key=VOTRE_CLE_API&lastModifiedDate=[01/01/2025,]&dollarsObligated=[0.0,100000000.99]&contractingDepartmentCode=9700" 

3. API SAM.gov Exclusions (Exclusions)

Documentation officielle : https://open.gsa.gov/api/exclusions-api/

Description : Permet de rechercher des entités et des individus qui ont été exclus, suspendus ou interdits de soumissionner à des marchés publics fédéraux.

Point de terminaison principal : GET https://api.sam.gov/entity-information/v4/exclusions

Paramètres de requête clés

• api_key : Requis
• q : Recherche en texte libre (prend en charge AND, OR, :, =, et le caractère générique *)
• ueiSAM / samUEI
• cageCode
• classification : Firm (Entreprise), Individual (Individu), Special Entity, Vessel
• exclusionType, exclusionProgram, excludingAgencyCode
• stateProvince, country, zipCode, addressLine1, addressLine2
• Filtres de date (unique ou plage) : activationDate, creationDate, updateDate, terminationDate
• page, size (taille max 10)
• includeSections : exclusionDetails, exclusionIdentification, exclusionActions, etc.

Exemple cURL

curl -X GET "https://api.sam.gov/entity-information/v4/exclusions?api_key=VOTRE_CLE_API&classification=Firm&stateProvince=VA" 

4. API SAM.gov Get Opportunities Public (Opportunités de marchés)

Documentation officielle : https://open.gsa.gov/api/get-opportunities-public-api/

Description : Permet de rechercher des opportunités de marchés en cours, des appels d'offres (solicitations), des pré-sollicitations et des avis d'attribution.

Point de terminaison principal : GET https://api.sam.gov/opportunities/v2/search

Paramètres de requête clés

• api_key : Requis
• postedFrom et postedTo : Requis (format MM/JJ/AAAA, plage maximale de 365 jours)
• title : Recherche par mot-clé dans le titre
• noticeType / ptype : p (Pré-sollicitation), a (Attribution), r (Appel d'offres), etc.
• solnum, noticeid
• organizationName, state, zip
• active : Yes / No
• limit (max 1000), offset : Pagination

Exemple cURL

curl -X GET "https://api.sam.gov/opportunities/v2/search?limit=10&api_key=VOTRE_CLE_API&postedFrom=01/01/2025&postedTo=05/10/2025&title=Driving" 

5. API SAM.gov Entity/Exclusions Extracts Download (Téléchargement d'extraits)

Documentation officielle : https://open.gsa.gov/api/sam-entity-extracts-api/

Description : Permet de télécharger de gros fichiers ZIP mensuels ou quotidiens contenant des ensembles complets de données publiques sur les entités ou les exclusions au format fichier plat (flat file).

Point de terminaison principal : GET https://api.sam.gov/data-services/v1/extracts

Paramètres de requête clés

• api_key : Requis
• fileName : Nom exact du fichier (ex: SAM_PUBLIC_MONTHLY_V2_AAAAMMJJ.ZIP)
• fileType : ENTITY ou EXCLUSION
• sensitivity : PUBLIC, FOUO, SENSITIVE (par défaut PUBLIC)
• frequency : MONTHLY (Mensuel) ou DAILY (Quotidien) (par défaut MONTHLY)
• charset : ASCII ou UTF8
• date : Date spécifique de l'extrait (MM/JJ/AAAA ou MM/AAAA)

Exemple cURL

curl -X GET "https://api.sam.gov/data-services/v1/extracts?api_key=VOTRE_CLE_API&fileName=SAM_PUBLIC_MONTHLY_V2_20220403.ZIP" 

Conclusion & Bonnes Pratiques

Ces API SAM.gov sont extrêmement précieuses pour l'ingestion de données publiques. Pour la plupart des projets de prototypes, commencez par utiliser les API Entity Management et Contract Awards. Veillez à toujours gérer correctement la pagination, à stocker votre clé API de manière sécurisée et à surveiller vos limites de requêtes. Reportez-vous à la documentation officielle pour obtenir la liste complète et à jour des paramètres.

Vous pouvez utiliser des outils comme Postman et les captures d'écran fournies pour effectuer vos tests.