{
  "openapi": "3.0.1",
  "info": {
    "title": "Ampersand Search API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://search.withampersand.com/v1"
    }
  ],
  "paths": {
    "/projects/{projectIdOrName}/integrations/{integrationId}": {
      "post": {
        "summary": "Search records",
        "description": "Search records in a SaaS instance.",
        "operationId": "searchRecords",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "projectIdOrName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integrationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "groupRef",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The group reference for the search request."
          }
        ],
        "requestBody": {
          "description": "Search request",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "title": "Search Request",
                "required": [
                  "objectName",
                  "fieldFilters"
                ],
                "type": "object",
                "properties": {
                  "objectName": {
                    "type": "string",
                    "description": "The name of the object to search.",
                    "example": "contact"
                  },
                  "fieldFilters": {
                    "type": "array",
                    "items": {
                      "title": "FieldFilter",
                      "type": "object",
                      "required": [
                        "fieldName",
                        "operator",
                        "value"
                      ],
                      "properties": {
                        "fieldName": {
                          "type": "string",
                          "description": "The name of the field to filter on. Could be a raw or mapped field name.",
                          "example": "email"
                        },
                        "operator": {
                          "type": "string",
                          "description": "The operator to use for the filter.",
                          "enum": [
                            "eq"
                          ],
                          "example": "eq"
                        },
                        "value": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "boolean"
                            },
                            {
                              "type": "number"
                            }
                          ],
                          "description": "The value to filter on. The type of the value is dependent on the field type.",
                          "example": "John Doe"
                        }
                      }
                    },
                    "description": "The field filters to apply to the search.",
                    "example": [
                      {
                        "fieldName": "email",
                        "operator": "eq",
                        "value": "example@example.com"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The search results",
            "content": {
              "application/json": {
                "schema": {
                  "title": "Search Response",
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "array",
                      "items": {
                        "title": "Search Result Entry",
                        "type": "object",
                        "description": "Each SearchResultEntry corresponds with a record in the SaaS provider (e.g. a Salesforce Account).",
                        "properties": {
                          "fields": {
                            "type": "object",
                            "description": "A key-value map of field names to values. This will only contain unmapped fields."
                          },
                          "mappedFields": {
                            "type": "object",
                            "description": "A key-value map of mapped field names to values."
                          },
                          "raw": {
                            "type": "object",
                            "description": "The raw data of the record, exactly as it is returned by the SaaS API.",
                            "additionalProperties": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The failure response for bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "title": "API Problem",
                  "type": "object",
                  "allOf": [
                    {
                      "title": "Problem",
                      "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n",
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that identifies the problem type",
                          "default": "about:blank"
                        },
                        "href": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML)."
                        },
                        "title": {
                          "type": "string",
                          "description": "A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).",
                          "example": "Service Unavailable"
                        },
                        "status": {
                          "type": "integer",
                          "format": "int32",
                          "description": "The HTTP status code generated by the origin server for this occurrence of the problem.",
                          "minimum": 400,
                          "maximum": 600,
                          "exclusiveMaximum": true,
                          "example": 503
                        },
                        "detail": {
                          "type": "string",
                          "description": "A human-readable explanation specific to this occurrence of the problem"
                        },
                        "instance": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced."
                        }
                      },
                      "example": {
                        "type": "urn:problem-type:exampleOrganization:exampleProblem",
                        "href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
                        "title": "Description of the type of problem that occurred",
                        "status": 400,
                        "detail": "Description of specific occurrence of the problem",
                        "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000"
                      }
                    }
                  ],
                  "properties": {
                    "subsystem": {
                      "type": "string",
                      "description": "The subsystem that generated the problem",
                      "example": "api"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time",
                      "description": "The time the problem occurred, formatted as RFC-3339",
                      "example": "2024-04-22T18:55:28.456076Z"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "A unique identifier for the request, useful for debugging",
                      "example": "89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715"
                    },
                    "causes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A brief description of something which caused the problem",
                        "example": "database connection failed"
                      },
                      "example": [
                        "database connection failed",
                        "database query failed",
                        "unable to fetch user"
                      ],
                      "description": "A list of problems that caused this problem. This can be used to represent multiple\nroot causes. There is no guaranteed ordering of the causes.\n"
                    },
                    "remedy": {
                      "type": "string",
                      "description": "A brief description of how to resolve the problem",
                      "example": "Shorten your input to be under 100 characters"
                    },
                    "supportEmail": {
                      "type": "string",
                      "format": "email",
                      "description": "An email address to contact for support",
                      "example": "support@withampersand.com"
                    },
                    "supportPhone": {
                      "type": "string",
                      "description": "A phone number to contact for support",
                      "example": "+1-555-555-5555"
                    },
                    "supportUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "A URL to contact for support",
                      "example": "https://withampersand.com/support"
                    },
                    "retryable": {
                      "type": "boolean",
                      "description": "Whether the request can be retried",
                      "example": false
                    },
                    "retryAfter": {
                      "type": "string",
                      "format": "date-time",
                      "description": "A timestamp after which the request can be retried, formatted as RFC-3339",
                      "example": "2024-04-22T18:55:28.456076Z"
                    },
                    "context": {
                      "type": "object",
                      "description": "Additional context for the problem",
                      "additionalProperties": true,
                      "example": {
                        "name": "Rick Sanchez"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "title": "API Problem",
                  "type": "object",
                  "allOf": [
                    {
                      "title": "Problem",
                      "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n",
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that identifies the problem type",
                          "default": "about:blank"
                        },
                        "href": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML)."
                        },
                        "title": {
                          "type": "string",
                          "description": "A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).",
                          "example": "Service Unavailable"
                        },
                        "status": {
                          "type": "integer",
                          "format": "int32",
                          "description": "The HTTP status code generated by the origin server for this occurrence of the problem.",
                          "minimum": 400,
                          "maximum": 600,
                          "exclusiveMaximum": true,
                          "example": 503
                        },
                        "detail": {
                          "type": "string",
                          "description": "A human-readable explanation specific to this occurrence of the problem"
                        },
                        "instance": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced."
                        }
                      },
                      "example": {
                        "type": "urn:problem-type:exampleOrganization:exampleProblem",
                        "href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
                        "title": "Description of the type of problem that occurred",
                        "status": 400,
                        "detail": "Description of specific occurrence of the problem",
                        "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000"
                      }
                    }
                  ],
                  "properties": {
                    "subsystem": {
                      "type": "string",
                      "description": "The subsystem that generated the problem",
                      "example": "api"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time",
                      "description": "The time the problem occurred, formatted as RFC-3339",
                      "example": "2024-04-22T18:55:28.456076Z"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "A unique identifier for the request, useful for debugging",
                      "example": "89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715"
                    },
                    "causes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A brief description of something which caused the problem",
                        "example": "database connection failed"
                      },
                      "example": [
                        "database connection failed",
                        "database query failed",
                        "unable to fetch user"
                      ],
                      "description": "A list of problems that caused this problem. This can be used to represent multiple\nroot causes. There is no guaranteed ordering of the causes.\n"
                    },
                    "remedy": {
                      "type": "string",
                      "description": "A brief description of how to resolve the problem",
                      "example": "Shorten your input to be under 100 characters"
                    },
                    "supportEmail": {
                      "type": "string",
                      "format": "email",
                      "description": "An email address to contact for support",
                      "example": "support@withampersand.com"
                    },
                    "supportPhone": {
                      "type": "string",
                      "description": "A phone number to contact for support",
                      "example": "+1-555-555-5555"
                    },
                    "supportUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "A URL to contact for support",
                      "example": "https://withampersand.com/support"
                    },
                    "retryable": {
                      "type": "boolean",
                      "description": "Whether the request can be retried",
                      "example": false
                    },
                    "retryAfter": {
                      "type": "string",
                      "format": "date-time",
                      "description": "A timestamp after which the request can be retried, formatted as RFC-3339",
                      "example": "2024-04-22T18:55:28.456076Z"
                    },
                    "context": {
                      "type": "object",
                      "description": "Additional context for the problem",
                      "additionalProperties": true,
                      "example": {
                        "name": "Rick Sanchez"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "title": "API Problem",
                  "type": "object",
                  "allOf": [
                    {
                      "title": "Problem",
                      "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n",
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that identifies the problem type",
                          "default": "about:blank"
                        },
                        "href": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML)."
                        },
                        "title": {
                          "type": "string",
                          "description": "A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).",
                          "example": "Service Unavailable"
                        },
                        "status": {
                          "type": "integer",
                          "format": "int32",
                          "description": "The HTTP status code generated by the origin server for this occurrence of the problem.",
                          "minimum": 400,
                          "maximum": 600,
                          "exclusiveMaximum": true,
                          "example": 503
                        },
                        "detail": {
                          "type": "string",
                          "description": "A human-readable explanation specific to this occurrence of the problem"
                        },
                        "instance": {
                          "type": "string",
                          "format": "uri",
                          "description": "An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced."
                        }
                      },
                      "example": {
                        "type": "urn:problem-type:exampleOrganization:exampleProblem",
                        "href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
                        "title": "Description of the type of problem that occurred",
                        "status": 400,
                        "detail": "Description of specific occurrence of the problem",
                        "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000"
                      }
                    }
                  ],
                  "properties": {
                    "subsystem": {
                      "type": "string",
                      "description": "The subsystem that generated the problem",
                      "example": "api"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time",
                      "description": "The time the problem occurred, formatted as RFC-3339",
                      "example": "2024-04-22T18:55:28.456076Z"
                    },
                    "requestId": {
                      "type": "string",
                      "description": "A unique identifier for the request, useful for debugging",
                      "example": "89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715"
                    },
                    "causes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A brief description of something which caused the problem",
                        "example": "database connection failed"
                      },
                      "example": [
                        "database connection failed",
                        "database query failed",
                        "unable to fetch user"
                      ],
                      "description": "A list of problems that caused this problem. This can be used to represent multiple\nroot causes. There is no guaranteed ordering of the causes.\n"
                    },
                    "remedy": {
                      "type": "string",
                      "description": "A brief description of how to resolve the problem",
                      "example": "Shorten your input to be under 100 characters"
                    },
                    "supportEmail": {
                      "type": "string",
                      "format": "email",
                      "description": "An email address to contact for support",
                      "example": "support@withampersand.com"
                    },
                    "supportPhone": {
                      "type": "string",
                      "description": "A phone number to contact for support",
                      "example": "+1-555-555-5555"
                    },
                    "supportUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "A URL to contact for support",
                      "example": "https://withampersand.com/support"
                    },
                    "retryable": {
                      "type": "boolean",
                      "description": "Whether the request can be retried",
                      "example": false
                    },
                    "retryAfter": {
                      "type": "string",
                      "format": "date-time",
                      "description": "A timestamp after which the request can be retried, formatted as RFC-3339",
                      "example": "2024-04-22T18:55:28.456076Z"
                    },
                    "context": {
                      "type": "object",
                      "description": "Additional context for the problem",
                      "additionalProperties": true,
                      "example": {
                        "name": "Rick Sanchez"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "title": "Search Request",
        "required": [
          "objectName",
          "fieldFilters"
        ],
        "type": "object",
        "properties": {
          "objectName": {
            "type": "string",
            "description": "The name of the object to search.",
            "example": "contact"
          },
          "fieldFilters": {
            "type": "array",
            "items": {
              "title": "FieldFilter",
              "type": "object",
              "required": [
                "fieldName",
                "operator",
                "value"
              ],
              "properties": {
                "fieldName": {
                  "type": "string",
                  "description": "The name of the field to filter on. Could be a raw or mapped field name.",
                  "example": "email"
                },
                "operator": {
                  "type": "string",
                  "description": "The operator to use for the filter.",
                  "enum": [
                    "eq"
                  ],
                  "example": "eq"
                },
                "value": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "number"
                    }
                  ],
                  "description": "The value to filter on. The type of the value is dependent on the field type.",
                  "example": "John Doe"
                }
              }
            },
            "description": "The field filters to apply to the search.",
            "example": [
              {
                "fieldName": "email",
                "operator": "eq",
                "value": "example@example.com"
              }
            ]
          }
        }
      },
      "FieldFilter": {
        "title": "FieldFilter",
        "type": "object",
        "required": [
          "fieldName",
          "operator",
          "value"
        ],
        "properties": {
          "fieldName": {
            "type": "string",
            "description": "The name of the field to filter on. Could be a raw or mapped field name.",
            "example": "email"
          },
          "operator": {
            "type": "string",
            "description": "The operator to use for the filter.",
            "enum": [
              "eq"
            ],
            "example": "eq"
          },
          "value": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "boolean"
              },
              {
                "type": "number"
              }
            ],
            "description": "The value to filter on. The type of the value is dependent on the field type.",
            "example": "John Doe"
          }
        }
      },
      "SearchResponse": {
        "title": "Search Response",
        "type": "object",
        "properties": {
          "result": {
            "type": "array",
            "items": {
              "title": "Search Result Entry",
              "type": "object",
              "description": "Each SearchResultEntry corresponds with a record in the SaaS provider (e.g. a Salesforce Account).",
              "properties": {
                "fields": {
                  "type": "object",
                  "description": "A key-value map of field names to values. This will only contain unmapped fields."
                },
                "mappedFields": {
                  "type": "object",
                  "description": "A key-value map of mapped field names to values."
                },
                "raw": {
                  "type": "object",
                  "description": "The raw data of the record, exactly as it is returned by the SaaS API.",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      },
      "SearchResultEntry": {
        "title": "Search Result Entry",
        "type": "object",
        "description": "Each SearchResultEntry corresponds with a record in the SaaS provider (e.g. a Salesforce Account).",
        "properties": {
          "fields": {
            "type": "object",
            "description": "A key-value map of field names to values. This will only contain unmapped fields."
          },
          "mappedFields": {
            "type": "object",
            "description": "A key-value map of mapped field names to values."
          },
          "raw": {
            "type": "object",
            "description": "The raw data of the record, exactly as it is returned by the SaaS API.",
            "additionalProperties": true
          }
        }
      }
    },
    "securitySchemes": {
      "APIKeyHeader": {
        "type": "apiKey",
        "name": "X-Api-Key",
        "in": "header"
      },
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "APIKeyHeader": []
    },
    {
      "Bearer": []
    }
  ]
}